Skip to content

Understanding the Check Token ID in PeopleTools 8.56

This is a guest post by a PeopleSoft security researcher.

PeopleSoft has introduced a new parameter on Node Definitions called the CheckTokenID. This parameter is required if you plan on using PeopleSoft Single Signon. In this post we will take a look at what exactly this Check Token feature is, how it works, and lastly some implications.

What is Check Token?

Check Token is a response from Oracle to combat vulnerabilities with PS_TOKEN and the ability to execute brute force attacks on the node password. Should the node password be recovered attackers would be able to create “authentic” PS_TOKENs. This was covered in a previous podcast

Check Token involves a set of low level changes to how the psp and psc servlets (and related Java code) handle the authentication process. These changes harden the servlets against such forged tokens.

However the process by which Check Token improves the security of PS_TOKEN is not very well detailed and for the remainder of this post we will look at the internals of how this set of changes improves security.

Check Token Pieces

The changes made in 8.56 for the Check Token feature can be split into 2 general sections:

  1. The Token Lookup
  2. The Knock Knock Request

The “Token Lookup” portion is a security precaution added to ensure that the PS_TOKEN being provided was actually issued by the PeopleSoft system.

The Knock Knock Request is a mechanism by which the target application can “phone home” to the site that generated the token and ask them if the Token is good.

We will go more into the details of how this is accomplished in the Step By Step section below.

Environment Setup

For the following sections assume that we have the following PeopleSoft Environments:

  • Interaction Hub (IH) on Tools 8.56
  • CRM on Tools 8.56
  • HCM on Tools 8.55

As part of configuring PeopleSoft SSO on 8.56, each Node that will participate (and is 8.56 or later) must have the Check Token ID field populated:

This CheckTokenID field must match for each node in each environment (for example, the IH node has the same value in IH and CRM, and the CRM node has the same value in IH and CRM).

Pressing the Create CheckTokenID button will securely generate a random 189 bytes (252 characters when encoded to base64). The page will also present you this value to copy out for use in the other environments.

You are able to specify any value you want for the CheckTokenID, but for the most security it is better to use the Create button.

There is more to the SSO setup than this, but this is the only portion relevant to the blog post.

An 8.56 SSO Event Step by Step

Now that the environments have been configured for SSO, the best way to show how Check Token works is to go Step by Step through an SSO event. That is when a user with an active session in the IH tries to access a page in CRM and triggers PeopleSoft SSO.

Initial Access

When a user hits a CRM page with a PS_TOKEN issued by IH, the psp or psc servlet initiates an authentication attempt by calling the authenticate method in the PSAuthenticator class (this is done in the servlet’s onLogin method). The PSAuthenticator class eventually calls an isAuthTokenValidFromRequest method. Inside this method it makes a couple of checks:

  1. Is the App Server a “portal” server
  2. Is this request from the “same site”

The “same site” is determined by looking at a cookie that is new to 8.56 called PS_LASTSITE.

If either 1 or 2 are true, then the “knock knock” portion of the CheckToken changes is not executed. In this scenario only the “Token Lookup” part is executed. The Token Lookup grabs the web server session (via the JSESSION cookie) and asks for the PS_TOKEN from the web server, it then compares this PS_TOKEN to the one that it has been presented and the check only succeeds if they match.

This in effect prevents forged tokens from being used, as they will be rejected since the token issued by the application itself wont match.

However, in our scenario the user just left IH and hit a CRM page. Because of this #1 isn’t true and PS_LASTSITE will be an IH url so #2 isn’t true. In this case the Authenticator starts the CheckToken “Knock Knock” portion.

CheckToken Request

Since CRM has decided that the Knock Knock should be performed, it begins the Knock Knock portion by calling doKnockKnockRequest of the PSCheckToken class.

The Knock Knock portion has the following steps:

  1. Get the Last Site (PS_LASTSITE cookie)
  2. Append ?cmd=checkToken to the URL from #1
  3. Form a POST request
  4. Send Request

The POST request is blank in terms of the content that gets posted, however it does contain a copy of all headers from the inbound request to CRM (including cookies like PS_TOKEN and JSESSION). The Request is sent off to the URL of the Last Site (in our case Interaction Hub) and PSCheckToken class waits for a response.

CheckToken Processing in IH

When IH receives the HTTP POST with ?cmd=checkToken the psp or psc servlet handles this in the process method. The process of handling the checkToken command is 2 steps, first IH will perform a “Token Lookup” action to ensure the IH really did issue this token. If IH did not, an exception is raised and CRM will not get a valid response.

If IH did issue the token it then begins to form the Knock Knock Response. At a high level the Knock Knock Response value consists of a digest and a nonce. A nonce is generated by using the generateNonce method of PSTrustAuthUtil this Nonce is generated by Base64 encoding 16 random bytes (source of random is SHA1PRNG).

The Digest itself is calculated by hashing the PS_TOKEN, the “knock knock constant”, the Nonce*, and the PS_TOKEN‘s issue date. The PSCheckToken class supports both SHA1 and SHA256, however the method createKnockKnockDigest appears to hard-code the algorithm to be SHA256.

The “knock knock constant” referenced above is simply the “hashed” version of CheckTokenID that was set on the Node Definition. Hashed is in quotes because its not truly a hash, but rather it is encrypted with the same algorithm that Node Passwords are. Try setting a node password and a CheckTokenID to the same value and then query the PSMSGNODEDEFN table to see that this is true.

Once the digest is calculated, the Nonce that was chosen by IH is then appended to the resulting hash and this value is set in the PS_CTDIGEST header. The * next to “Nonce” is because there seems to be a cryptographic oversight (at least in the 8.56 versions I’ve looked at). When using SHA1 the Nonce is correctly included in the hashing, but when SHA256 is used the Nonce is NOT included in the hash like it should be: ![Nonce Issue for SHA256][2]

CheckToken Response Processing

Once IH has generated the response and sent it back to CRM, the CRM application server continues execution of replyFromKnockKnockRequest in the PSCheckToken class. This method retrieves the PS_CTDIGEST header and splits the value into 2 parts, the digest and the nonce. This is doable because hashes have a determinate length so it is easy to grab the Nonce off the end.

Once the values are split CRM goes ahead and generates the same digest, using its copy of the CheckTokenID value for the appropriate node as well as the Nonce*. If the generated digest matches the digest that IH sent, authentication succeeds and the user is successfully SSO’d into CRM! The * next to “Nonce” is for the same reason as earlier.

Applications < 8.56

As mentioned in the environment setup we are pretending to have an HCM environment that is below 8.56. Let’s briefly discuss how Oracle kept compatibility for this mode of operation (IH on 8.56 and other apps lower than that).

The way Oracle engineered this change puts the responsibility of determining when to enforce CheckToken on the target application (the one that is being SSO’d to). Oracle deliberately made no changes to the format of PS_TOKEN itself so that tokens issued by 8.56 would still be valid on 8.55 systems.

Because our HCM environment knows nothing about Check Token, it will never determine that it needs to ask the IH to check the PS_TOKEN. And because of this the PeopleSoft SSO operates effectively the same way it has been.

What about that Nonce thing?

As mentioned above there seems to have been an oversight with the generation of the Knock Knock response when using SHA256 (not including the Nonce in the hash). Nonce’s are intended to prevent the ability to replay a request. So while technically the lack of the Nonce in the hash renders this protection moot, ultimately the attacker would not be able to get back to “Token Lookup” phase with a forged token because the Application Server will not find that token as not having been issued.

What is important to note is that should Oracle release patches to fix this oversight, they would need to be applied to all systems, if only applied to the CRM in our example, the digest that IH produces would no longer match what CRM produces.

20 thoughts on “Understanding the Check Token ID in PeopleTools 8.56”

  1. Thanks for sharing this article – Recently, we upgraded IH and HCM to PT8.56 and single sign has stopped working – I see Pressing the Create CheckTokenID button is a generating a token on local nodes both applications – I can’t locate anywhere in Node Definintions, Connectors, Portal or WS Security tabs to define this token on receiving node – Where should I define the this generated token on receiving node ? I would really appreciate if you could elaborate more this ?

      1. Copy the value generated out of the local node into the value in the remote (receiving) node.

        “Pressing the Create CheckTokenID button will securely generate a random 189 bytes (252 characters when encoded to base64). The page will also present you this value to copy out for use in the other environments.”

        The “other environments” is referring to the associated node in the remote database.

  2. Hello Dan,
    Have you tried to configure this setup using a load balancer (Netscaler or F5) across 2 webservers? It appears when the “content system” is validating the token against the “token issuing system” the “token issuing system” is throwing an illegal token switch message because it is unable to find the jsessionID on the other webserver.

    When we have only one webserver everything seems to be working fine.

    1. Hi,

      We are experiencing the same issue. we are trying to use single signon from HCM 9.2 Tools 8.55 to Campus 9.2 Tools 856.

      This is working fine on single webserver setup, but on load balanced dual webserver setup we are having connection issues.

      Did you mange to resolve your issue?

      1. 8.55 does not use check token, so I don’t believe this is related to check token. It must be something else. What connection issues are you seeing any errors?

    2. Hi Venkat,

      Just wonder if you have this issue resolved using F5 as load balancer?
      We are having same issue here after upgraded to 8.56. It would be much appreciated if you could share with us.



      1. We used netscaler but I believe the setup would be similar in F5 as well. The key is to setup session persistence using cookie instead of using IP address. The domain of the cookie set by netscaler should match the authentication domain of your peoplesoft.

        Check out document 2364547.1.

        1. Thank you Venkat for your prompt reply and assistance.
          Yes I have seen that document on Oracle support site. Our F5 has always been set up as using session persistence, even when we were on Tool 8.53. This has not been changed.
          Yesterday I found something which resolved half of the issue. I found out that at the end of the URL there is a & symbol which upsets the SSO, if I remove the & symbol, the single sign on to PeopleSoft home page works fine. But looks like 8.56 does differntly of constructing URLS in web server configuration. I remember in 8.53 I fixed that in the signon.html file, but cannot see this in 8.56 signon.html. Do you know where else I could check?
          I said this fixed half of the issue, because SSO works for log into home page. But when someone clicks link in email for leave request or leave approval from HCM, it still requires log in twice. Not sure if you guys have this issue as well?
          Thanks alot

          1. I don’t think the issue you are describing has anything to do single signon. Do you have multiple systems like interaction hub, financials and HRMS?

            If all you have is HRMS and the links from the emails are not auto logging you in, it might be a bug, refer to 2409127.1

          2. Vincent, We are experiencing the exact issue you described in your post. Do you remember how you fixed this issue?

  3. 8.55 does not use check token, so I don’t believe this is related to check token. It must be something else. What connection issues are you seeing any errors?

  4. can we able to short the token from 252 characters when encoded to base64 to 10-15 characters with encoded to base 64.

  5. Do you know if sso works when the initial token is issued by an 8.55 pt (ih) an the target is 8.56 ? Since Last site was not set by the first, the latter does not know where to knock?

    1. Sharing :
      This is not a supported combination when PIH (Portal) is lower tools version than Content provider databases (FSCM)
      The constraints coming from the past portal integration models were that Portal to be at same or equal tools version than all the rest of PSFT databases integrated in the PIH cluster
      For Unified Navigation that is the only model that supports new 9.2 application features from remote databases the new rule is to have all databases at precise same tools patch whichever the tools version would be

      At this moment you have two options
      1. The recommended way:1. Get the PIH database at PT 8.57.10 patch as well al the rest of clustered other databases

      Not recommended by our security!!! – this as far this wrong tools combination was never imagined to be supported
      Downgrade the FSCM security (disable the check-token)
      How : in FSCM database add a custom line in webprofile used by your site like below
      WebCheckToken – boolean – false

  6. Hi Dan,

    We are trying to re-establish PeopleSoft only SSO between HCM 9.2 on PT8.57 and ELM 9.2 on PT 8.55.
    SSO was working fine until we upgraded the HCM application from PT 8.55 to PT 8.57.

    In our case ELM application which is on PT 8.55 is trying to SSO onto HCM application which is on PT 8.57 to fetch HR data onto ELM application.

    Since, HCM application is on PT 8.57, we have CheckTokenID field in the node definition page. We generated the CheckTokenID by clicking the Create CheckTokenID button of the local node (i.e. PSFT_HR).
    But ELM application which is on PT 8.55 don’t have CheckTokenID field. Hence, we can’t update the CheckTokenID for neither the external node (in our case PSFT_HR for ELM application) nor create CheckTokenID for PSFT_LM node of the ELM application.

    When we try to SSO from ELM to HCM, we are getting below error message instead of the HCM page.
    “Unauthorized Token has been detected by the System. Please signon with your Userid and Password”

    We have checked the solution offered in the MOS post “E-PIA: PT 8.56x SSO Troubleshooting Tips due to CheckTokenID feature (Doc ID 2427220.1)”.

    It would be much appreciated if you could share how you configured the SSO between IH (8.56) and HCM (8.55) for your testing purpose.


    1. Hi Abhishek – you won’t be able to SSO from an 8.55->8.57 environment that has Check Token enabled. That is a limitation of the feature. You can go from 8.57->8.55 though, but not the other way around.

    2. Try to disable the check token feature on 8.57.

      In web profile go to custom properties tab and add

      WebCheckToken Boolean false

      And bounce the web servers.

      1. Thanks Venkat and Dan for your advice. Much appreciated!
        We have implemented the adding custom property (WebCheckToken Boolean false) solution in the web profile and it worked for us though it downgrade the PS security to PT 8.55 level to make our SSO work between ELM (PT8.55) to HCM (PT8.57).



Leave a Reply

Your email address will not be published. Required fields are marked *