Proxy-Credential User Switching in Signon PeopleCode

Every so often a backend service — a reverse proxy, a mobile app backend, a portal, an integration bus — needs to call PeopleSoft web services on behalf of an end user who has already been authenticated somewhere else (Azure AD, Okta, Ping, whatever your IdP is). The backend has a real user in mind. It just doesn’t have, and shouldn’t have, that user’s PeopleSoft password.

The usual answers are all a little unsatisfying:

• Have the backend collect the end-user’s password and replay it to PeopleSoft. This is what most LDAP-bind mobile integrations ended up doing, and it’s exactly the path most security teams are now trying to retire.
• Use PeopleTools OAuth2. On paper this is the right answer. In practice the current implementation has enough rough edges — rigid claim mapping, reliance on PSUSEREMAIL as an identity key, a single-IdP ceiling, opaque error messages — that it’s a poor fit for a lot of real-world user populations. I wrote up the details and the Oracle support-case evidence at PeopleSoft REST OAuth2 . More on where it does and doesn’t fit below.
• Generate a PS_TOKEN natively in PeopleCode by reconstructing the token format and signing it with the node key. This is the approach Colton Fisher describes on peoplesoftmods.com . Clever, and it works — but it depends on undocumented internals and requires code that can read the node signing material. I wouldn’t put it in production because a PeopleTools patch could change the token format or signing mechanism and break it without warning.

There is a fourth option that I like a lot better, and it’s built entirely out of documented PeopleSoft APIs: proxy-credential user switching inside Signon PeopleCode.

The Short Version

The backend service holds a dedicated PeopleSoft service account — a normal OPRID with a normal password, that you own and can rotate. When it needs PeopleSoft data for a specific end user, it authenticates to a custom iScript as that service account and passes the target user’s OPRID in a custom HTTP header (X-Switch-User). A Signon PeopleCode hook recognizes the service account, validates the target against an allow-list, and calls SetAuthenticationResult(True, <target OPRID>, "", False) to switch the session to the target user. The iScript then returns a normal PS_TOKEN for the target.

The end user’s password is not required to be sent to PeopleSoft. The token that gets minted is identical to one that would have been issued through your normal signon path — because it is issued through your normal signon path. No undocumented internals, no node keys in PeopleCode, no bypassing Signon PeopleCode or any of the hooks that normally fire (Appsian/Pathlock, audit, whatever else you’ve bolted on).

A nice side effect: MFA enforcement stays at your IdP. The end user already went through whatever MFA policy the IdP enforces when they signed into the front-end app. Since their password isn’t being replayed to PeopleSoft at all, there’s no second credential collection and no LDAP bind quietly succeeding on a password alone while the IdP’s MFA is left at the door.

  sequenceDiagram
    autonumber
    participant User as End User (Device)
    participant Backend as Backend Service
    participant PS as PeopleSoft
    participant Signon as Signon PeopleCode Hook
    participant IScript as Token-Mint iScript

    User->>Backend: Sign in (IdP)
    Note over User,Backend: Later, user needs PeopleSoft data
    Backend->>PS: POST IScript_Switch<br/>userid: SVC_ACCOUNT<br/>pwd: ***<br/>X-Switch-User: JSMITH
    PS->>Signon: signon pipeline fires
    Note over Signon: Is %SignonUserId = SVC_ACCOUNT?<br/>Is %PSAuthResult = True?<br/>IsAllowedSwitchTarget("JSMITH")?
    Signon->>PS: SetAuthenticationResult(True, "JSMITH", "", False)
    PS->>IScript: execute as JSMITH
    IScript-->>Backend: 200 OK + PS_TOKEN cookie for JSMITH
    Backend->>PS: subsequent web service calls<br/>Cookie: PS_TOKEN
    PS-->>Backend: data
    Backend-->>User: render feature

Why This Works: SetAuthenticationResult

The whole trick hinges on a function that has been in PeopleTools for a very long time: SetAuthenticationResult. Inside Signon PeopleCode, you can overwrite the outcome of the current authentication attempt — who PeopleSoft considers the signed-in user, whether authentication succeeded, and whether to force a password change.

The first argument is “did authentication succeed?” The second is “who is the user?” If you pass True and an OPRID other than the one that was submitted, PeopleSoft cheerfully mints a session as that other user. That’s the entire mechanism.

This is not a hack. It’s the documented behavior of the function and it’s what makes things like SAML, Kerberos, certificate-based signon, and every other “trust-another-system” login pattern possible. We’re using it for a slightly different purpose — trusting our own backend service rather than an external IdP — but the mechanism is identical.

The Signon PeopleCode

Here’s the hook, with the critical gates called out:

Function IsAllowedSwitchTarget(&sOprid As string) Returns boolean
   /* Production implementation: gate on your real authorization rule.
      Examples: active employees, active students, an explicit allow
      table, or a join against some attribute on PSOPRDEFN. */
   Return True;  /* placeholder for a PoC only */
End-Function;

Function SVC_SWITCH_USER()
   /* 1. Only intervene for our dedicated service account.
         Every other signon flows through untouched. */
   If %SignonUserId <> "SVC_ACCOUNT" Then
      Exit;
   End-If;

   /* 2. Password auth must have already succeeded for the service
         account. If the caller didn't send the right password,
         %PSAuthResult is False and we refuse — the service-account
         password is the outer gate. */
   If Not %PSAuthResult Then
      Exit;
   End-If;

   Local string &sTarget;

   try
      &sTarget = Upper(%Request.GetHeader("X-Switch-User"));
   catch Exception &e
      /* %Request not available — fail safe */
      SetAuthenticationResult(False, %SignonUserId, "", False);
      Exit;
   end-try;

   If None(&sTarget) Then
      /* No header = authenticated as the service account but didn't
         ask to switch. The service account has no useful permissions
         of its own, so this will naturally 403 at the iScript. */
      Exit;
   End-If;

   /* 3. The authorization gate. This is the only thing standing
         between the service account and every user it could
         impersonate. Treat it with the respect it deserves. */
   If IsAllowedSwitchTarget(&sTarget) Then
      SetAuthenticationResult(True, &sTarget, "", False);
   Else
      SetAuthenticationResult(True, %SignonUserId, "", False);
   End-If;
End-Function;

Three gates, in order: is this the proxy account, did the proxy password check out, is the requested target allowed. Anything else falls through to normal signon behavior and the hook is inert.

Note the structure of the %Request.GetHeader call — it’s wrapped in a try/catch because %Request is only available when Signon PeopleCode fires from a web-facing signon. If you ever call this hook from a context where %Request isn’t there, you want to fail closed rather than swallow an exception.

You have to activate this as Signon Peoplecode like this:

The iScript

The iScript itself is almost nothing. It just needs to exist, because the act of executing an iScript is what triggers the signon pipeline and returns a PS_TOKEN cookie for whoever is authenticated at the end of that pipeline. The body of the iScript’s job is basically to report back to the caller what happened — the resolved OPRID, optionally some other identifying information, and the token itself — so the backend doesn’t have to parse the Set-Cookie header.

A minimal implementation in a WebLib record looks like this:

Function IScript_Switch()

   /* At this point Signon PeopleCode has already run. If the allow-list
      rejected the switch, %UserId is still the proxy user and we 403.
      If the switch succeeded, %UserId is the target user. */
   If %UserId = "SVC_ACCOUNT" Then
      %Response.SetHeader("Content-Type", "application/json; charset=utf-8");
      %Response.WriteLine("{""error"":""forbidden""}");
      %Response.SetStatusCode(403);
      Return;
   End-If;

   Local JsonObject &json = CreateJsonObject();
   &json.AddProperty("OPRID", %UserId);
   &json.AddProperty("EMPLID", %EmployeeId);

   /* PeopleSoft has already set PS_TOKEN in the response cookies
      via the normal signon pipeline. We echo the value in the body
      so the calling service doesn't have to parse Set-Cookie. */
   &json.AddProperty("PS_TOKEN", %AuthenticationToken);

   %Response.SetContentType("application/json; charset=utf-8");
   %Response.Write(&json.ToString());

End-Function;

The iScript lives in a custom WebLib (for example WEBLIB_C_TOKEN.ISCRIPT1.FieldFormula.IScript_Switch). Target users must have permission to that WebLib — typically via a permission list granted to every user who might be on the allow-list. Without that grant, the signon pipeline will switch to the target user but the iScript itself will refuse to execute.

A representative request:

POST /psc/ps/EMPLOYEE/SA/s/WEBLIB_C_TOKEN.ISCRIPT1.FieldFormula.IScript_Switch?disconnect=y&postDataBin=y
userid: SVC_ACCOUNT
pwd: ***
X-Switch-User: JSMITH

Response:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
set-cookie: PS_TOKEN=ogAAAAQDAgEBAAAAvAIAAAAA...; HttpOnly

{
  "OPRID": "JSMITH",
  "EMPLID": "K0001234",
  "PS_TOKEN": "ogAAAAQDAgEBAAAAvAIAAAAA..."
}

PeopleSoft thinks it just authenticated JSMITH — and from its perspective, it did. Every downstream web service call that carries that PS_TOKEN cookie will be evaluated against JSMITH’s permissions.

A “Who Am I” service for verification

When you’re standing this up it helps to have a trivial web service that just echoes the authenticated user back.

If you need an overview of how to set this up see this A Complete PeopleSoft REST GET Web Service Example article. The handler code is basically this:

import PS_PT:Integration:IRequestHandler;

class whoAmI_handler implements PS_PT:Integration:IRequestHandler
   method OnRequest(&msgRequest As Message) Returns Message;
end-class;

method OnRequest
   /+ &msgRequest as Message +/
   /+ Returns Message +/
   /+ Extends/implements PS_PT:Integration:IRequestHandler.OnRequest +/

   Local Message &response;
   &response = CreateMessage(@("Operation." | &msgRequest.OperationName), %IntBroker_Response);

   Local JsonObject &root = CreateJsonObject();
   &root.AddProperty("OPRID", %OperatorId);
   &root.AddProperty("EMPLID", %EmployeeId);

   &response.SetContentString(&root.ToString());
   Return &response;
end-method;

And the call:

GET /PSIGW/RESTListeningConnector/PSFT_CS/C_AUTH_WHOAMI.v1/
Cookie: PS_TOKEN=ogAAAAQDAgEBAAAAvAIAAAAA...

{ "OPRID": "JSMITH", "EMPLID": "K0001234" }

If this returns your target user, the mint worked and the token is behaving like any other PS_TOKEN. If it returns the proxy user, your allow-list rejected the target. If it 401s, the token didn’t mint — check the signon log.

Downstream Service Compatibility Is Not Free

Worth calling out, because it bit the PoC: not every PeopleSoft web service will happily accept a minted token. Most will — the token is structurally identical to one from any other signon path. But a small number of services have their own authentication expectations layered on top of Integration Broker’s. Delivered campus solutions services like SCC_USERREG_AUTH.v1/authenticate are a good example; they expect to be the thing doing authentication and don’t necessarily accept a pre-minted cookie as proof of identity.

Why You Want a Custom iScript and Not “Just a Web Service”

It’s tempting to say: why not do this from a regular PeopleSoft REST service? The answer is that the token minting has to happen inside the signon pipeline. SetAuthenticationResult is only meaningful there. An ordinary REST service handler runs after authentication has completed and the PS_TOKEN has already been issued to whoever authenticated — too late to redirect the session to a different user.

An iScript, executed through the portal servlet, runs through the full web signon pipeline every time it’s invoked. That’s what makes the signon hook fire, and that’s what produces a token the rest of PeopleSoft will accept on equal footing with a token from a SAML or LDAP login.

If you try to roll your own token minter outside the signon path, you are back in the territory of the “generate PS_TOKEN natively” approach — reconstructing internal formats, signing with the node key, and hoping a patch doesn’t change anything. Don’t.

Security — Read This Part Carefully

This pattern is powerful. It is also, by design, a privilege escalation tool. The proxy service account, with a valid password and a permissive allow-list, can mint a PS_TOKEN for any user in the allow-list without ever knowing that user’s password. Treat that capability with appropriate fear.

A non-exhaustive list of what you need to get right before this goes anywhere near production:

• The service account is a crown-jewel credential. Long, high-entropy password. Stored in a real secrets manager. Rotated on a real schedule. Never in source control, never in a config file on a shared drive, never pasted into a ticket.
• Network-level allow-list. If you have a reverse proxy / WAF in front of PeopleSoft (Appsian/Pathlock, F5, whatever), restrict the iScript path to the egress IPs of the backend service that is allowed to call it. If you don’t, any attacker who exfiltrates the service-account password can use it from anywhere.
• IsAllowedSwitchTarget is the authorization boundary. It is the only thing distinguishing “the backend can mint a token for a specific student/employee/whatever” from “the backend can mint a token for anyone in the system, including your PeopleSoft administrators.” Review this function like you would review a privileged SQL grant. Unit-test it. Require a formal review on every change. At minimum, scope it to a population that is much smaller and less privileged than the general user base. For a student-facing mobile app, an allow-list of “active students only” is reasonable. An allow-list of “any OPRID in PSOPRDEFN” is a loaded footgun.
• No administrators on the allow-list. Ever. IsAllowedSwitchTarget should explicitly reject anyone with elevated roles — PeopleSoft Administrator, anyone with sensitive permission lists, anyone who can change the allow-list itself. Put that check in the function, not in the spec document.
• Audit every mint. Log source IP, proxy OPRID, requested target, allow-list decision, timestamp, and outcome for every call. Monitor for anomalies — mint-rate spikes, allow-list denials, failures on the proxy credential. If you can’t see it, you can’t catch it when it goes wrong.
• The hook must be narrow. SVC_SWITCH_USER should act only on the proxy account and only after %PSAuthResult is true. It should be inert for every other signon on the system. The If %SignonUserId <> "SVC_ACCOUNT" Then Exit; guard at the top is not optional — it is the reason the rest of your authentication stack continues to function normally.
• This is not something you grant to three different teams. If five different backend services want this pattern, they each get their own service account, their own hook, and their own allow-list — with separate logging and separate rotation. Do not consolidate. Do not share.

Put differently: anyone who ends up with the service account password and network access to the endpoint can act as any user on the allow-list. The only things standing between that credential and impersonation of your entire user base are the allow-list logic and your operational discipline. If either of those is weak, this pattern is worse than the thing it replaced.

Where This Fits vs. OAuth2

If PeopleTools OAuth2 works for your population, use it. It’s the direction most enterprises are going and it doesn’t require you to operate a privileged shared credential. I have a longer writeup, including an Oracle support-case trail documenting where it breaks down in practice, at PeopleSoft REST OAuth2 . The short version of why OAuth2 is often a bad fit today:

• Rigid, case-sensitive claim mapping with no PeopleCode hook. The JWT sub claim must be a valid OPRID and the email claim must exactly match PSUSEREMAIL. There is no place to translate a claim into an OPRID yourself. If PSUSEREMAIL is incomplete, wrong-cased, or scrambled — normal states in non-production, and common for self-service user populations even in production — OAuth2 fails with an opaque invalid_token and you get very little visibility into why.
• PSUSEREMAIL is unreliable for many populations. Student and other self-service populations are the least likely to have clean, populated email rows in PSOPRDEFN. The users you most need this to work for are often exactly the users it won’t work for.
• Single-IdP ceiling. PeopleSoft accepts one OAuth2 authorization server globally. Any future integration requiring a different IdP is blocked.
• Thin tooling. Error surface is minimal, documentation is sparse, and debugging claim-mapping problems is painful.

The proxy-credential pattern sidesteps all of that because target resolution is just PeopleCode. IsAllowedSwitchTarget can look up the target by EMPLID, by email, by some PSOPRALIAS row, by whatever attribute is actually reliable in your database, in whatever casing you have. You write the lookup yourself, you can log it, you can test it, and you don’t depend on every user in your allow-list having a perfectly-populated PSUSEREMAIL.

Think of it as a stopgap with a long shelf life: useful today, and useful to keep around when OAuth2 doesn’t fit the user population or the integration pattern.

A Variation: Reverse-Proxy SSO With the Same iScript

So far this has been a backend-service story — an integration acting on behalf of an end user who is somewhere else. But the iScript doesn’t actually care who is calling it. The Signon PeopleCode is unchanged, the SetAuthenticationResult call is unchanged, the PS_TOKEN it produces is unchanged. The only thing that needs to change for an interactive SSO front door is the caller — and what the caller does with the token. Put a reverse proxy in front of PeopleSoft, give it a real IdP integration, and you have an SSO solution.

The flow is short:

1. The user’s browser hits the reverse proxy. They have no PS_TOKEN yet.
2. The proxy runs them through the IdP (SAML, OIDC, whatever).
3. The proxy resolves the IdP identity to a PeopleSoft OPRID — exactly the kind of lookup IsAllowedSwitchTarget already encapsulates.
4. The proxy back-channels into the iScript: userid=SVC_ACCOUNT, pwd=***, X-Switch-User: <oprid>. PeopleSoft mints a PS_TOKEN for the target user and returns it in the JSON body (and as Set-Cookie).
5. The proxy issues its own Set-Cookie: PS_TOKEN=... to the user’s browser, then either redirects them to the PeopleSoft URL or just forwards their original request along with the cookie attached.

  sequenceDiagram
    autonumber
    participant Browser as User Browser
    participant Proxy as Reverse Proxy
    participant IdP
    participant IScript as Token-Mint iScript
    participant PS as PeopleSoft Web

    Browser->>Proxy: GET app URL (no PS_TOKEN yet)
    Proxy->>IdP: SAML or OIDC handshake
    IdP-->>Proxy: authenticated identity
    Note over Proxy: resolve identity to OPRID
    Proxy->>IScript: POST IScript_Switch<br/>userid: SVC_ACCOUNT<br/>pwd: ***<br/>X-Switch-User: JSMITH
    Note over Proxy,IScript: same iScript and Signon PeopleCode<br/>as in the earlier diagram
    IScript-->>Proxy: 200 OK + PS_TOKEN for JSMITH
    Proxy-->>Browser: Set-Cookie PS_TOKEN<br/>302 redirect to original URL
    Browser->>Proxy: GET original URL<br/>Cookie carries PS_TOKEN
    Proxy->>PS: forward request and cookie
    PS-->>Browser: PeopleSoft session as JSMITH

The whole thing only works if the proxy can push a PS_TOKEN cookie that the user’s browser will then send back when it lands on PeopleSoft. Browsers only return a cookie to hosts the cookie’s Domain attribute permits, which means the URL the user sees in their address bar and the URL PeopleSoft serves on have to share a cookie scope. Two configurations make that work:

• Single hostname. The reverse proxy is the only public URL — say myhr.example.com. The PeopleSoft web server is internal-only and never exposed directly. Every browser request transits the proxy. The cookie can be a host-only cookie (no Domain attribute) and it just works.

• Shared parent domain. The proxy lives at sso.example.com, PeopleSoft at ps.example.com. The PeopleSoft web profile’s Authentication Domain (PS_TOKENDOMAIN) is set to .example.com, and the proxy issues the cookie with a matching scope:

  Set-Cookie: PS_TOKEN=ogAAAAQDAgEBAAAAvAIA...; Domain=.example.com; Path=/; Secure; HttpOnly; SameSite=Lax
  

The cookie attributes — Domain, Path, Secure, HttpOnly, SameSite — are now part of the trust boundary. They have to match what PeopleSoft itself would have set, or the browser will quietly drop the cookie on the next request and you’ll spend an afternoon staring at a clean signon log and a 401.

Functionally this is the same shape as a Shibboleth, F5 BIG-IP APM, Okta Access Gateway, or Appsian/Pathlock front-end — see SAML Alternatives for PeopleSoft for the vendor field guide. The difference is mechanical: those products typically inject HTTP headers (REMOTE_USER or similar) and lean on Signon PeopleCode to read them; this pattern injects the PS_TOKEN cookie directly so PeopleSoft sees a session that’s already been established. Both are legitimate. This one happens to be a few hundred lines of glue rather than a licensed product.

Everything in the security section still applies. A few things to add specifically for the reverse-proxy mode:

• The proxy must be the only path. If a user can reach the PeopleSoft web server directly, they can sidestep the IdP entirely. Network-level enforcement, not just a config knob.
• Cookie attributes are part of the boundary. A Set-Cookie without Secure leaks the token to any HTTP request on the domain. An overly broad Domain (.example.com when only myhr.example.com should see it) leaks it to every sibling. Get these right.
• The service-account password lives inside the reverse proxy now. That makes the proxy itself a crown-jewel system. Patch it, monitor it, lock down who can deploy to it.
• The allow-list shifts in scope. It is no longer “the small set of users a backend integration acts on behalf of” — it is “the population allowed to interactively sign on this way.” Typically broader, but administrators are still excluded unconditionally. That rule does not relax.

When Not To Use This

• Interactive user logins as a directly exposed endpoint. Don’t expose the iScript directly to end-user browsers as a signon URL — there’s no IdP in front of it, no MFA, and the trust model collapses to “anyone who can reach the iScript and guess the service-account password.” A reverse proxy that authenticates the user against a real IdP and then back-channels into the iScript is a different shape (covered above ) — that one is fine. The iScript as a public-facing login form is not.
• “Convenience” integrations that could use end-user credentials legitimately. If a user is sitting in front of the screen and can authenticate directly, let them. This pattern is for service-to-service flows where the end user is somewhere else and has already been authenticated by some other system.
• Any case where the allow-list would need to include privileged users. If the use case requires impersonating administrators, you have a different problem. Don’t solve it with this.

Closing

Switching users inside Signon PeopleCode via a proxy credential is an old idea made newly useful by the number of backend services that now need to act on behalf of users authenticated somewhere else. It beats replaying end-user passwords, it doesn’t depend on undocumented token internals, and it coexists cleanly with whatever else you have in your signon pipeline.

It is also a loaded gun. Grant it sparingly, scope the allow-list narrowly, protect the service account aggressively, and log everything. Done with discipline, it’s a durable pattern. Done carelessly, it’s a back door with your name on it.