Jarek Cora (Jarek)
Director, Engineering
Jarek Member since 2013 7 posts
Posted: December 13, 2018
Last activity: January 14, 2021
Posted: 13 Dec 2018 9:17 EST
Last activity: 14 Jan 2021 12:55 EST

Troubleshooting OpenID Connect (OIDC) integrations

Pega Platform can be configured to authenticate against any external Identity Provider (IdP) which supports OpenID Connect (OIDC) protocol. See for example how to do it with Okta, Auth0 or miniOrange.

In most cases such integration is straightforward and works on the first try. Sometimes however a bit of troubleshooting may be required. This article describes tools and techniques useful in investigating problems with integrations of Pega Platform with external Identity Providers.

Pega Platform logs

The first troubleshooting tool is a properly configured Pega Platform log. In Developer Studio, go to Configure > System > Operations > Logs and click "Logging level settings". Find the logger corresponding to OIDCClientHandler and set the log level to "ALL".

This will give you detailed logs for each authentication attempt involving OIDC. For example, if your Pega Platform is configured with Okta as described here, the logs for a single successful authentication look like this:

Initiating OIDC flow
Constructing authorization URL for OIDC provider
Constructed authorization URL for OIDC provider : https://dev-500306.oktapreview.com/oauth2/...
Processing authcode received from OIDC provider
Fetching access token using authCode received
Successfully fetched access token and ID token using authCode
Validating ID token received from access token end point eyJraWQiOiJ5dVBUeVBUUEdjcE1WamxpNE...
Successfully validated ID token with standard claims
Retrieving userInfo claims from user info Endpoint
Fetch operator from claim {email} from received ID token claims
Successfully established operator from received ID token claims
Successfully authenticated operator with OIDC flow

The most useful part of the log is the ID token, which you can see in line 7 of the example above. In order to extract human-readable information from the ID token, we will use a 3rd party tool.

JWT Debugger

JWT Debugger provided by Auth0 allows to decode any JWT token and verify its signature. Copy paste the token from your log files into the "Encoded" field of the debugger. The "Decoded" filed will show you the header and payload of your token in form of easy to read JSON objects. This allows you to see information specific to the user who attempted to log in, such as name and email, and information specific to the integration.

You can now compare information from the token with information from the authorization request initiated by Pega. Take a closer look at line 3 of the log file. It contains the authorization URL with a number of parameters, in particular:

  • client_id = 0oagl4s7p9LyhbUop0h7
  • nonce = 460b76114f7dc13c9de8f92d67de57877bf95b5fc6f71b26d6df1a3cd6b1591e

You should verify that:

  • Audience ("aud") from the token matches the client_id from the request parameters
  • Nonce ("nonce") from the token matches the nonce from the request parameters
  • Additionally, that issuer (“iss”) from the token matches the Issuer in your Pega authentication service configuration

JSON Web Token debugger allows you to also verify the token signature. In order to do it, you need to locate the public key corresponding to unique key identifier ("kid") from the ID token header. The key is available in the keystore used by your Pega authentication service. Go to the authentication service configuration and open the keystore associated with the service.

In case of our Okta example it looks like this:

Download the keystore from the URL. It's a JSON file so you can open it in a text editor, but it's much more convenient to use yet another tool.

JQ Play

JQ Play service allows to conveniently view and manipulate JSON files in a web browser. Paste the contents of the downloaded JWKS keystore into the "JSON" field and enter . (dot) as the filter. This will show the contents of the keystore in a nicely formatted form in the "Result" field.

Find the key with "kid" corresponding to the "kid" from the ID token. In our example the "kid" in ID token header in JSON Web Token debugger is "yuPTyPTPGcpMVjli4CcYXHZU0rBU3Jl_ODGN9-3UjOs". It corresponds to the first key in the keystore displayed in JQ Play.

Copy the whole key, from { to } characters, and paste it into the field labeled "Public Key or Certificate" in the JWT Debugger.

Pasting this key into JWT Debugger triggers the signature verification and if successful, shows the "Signature Verified" message.


In case an integration is not working and it's difficult to identify whether the problem is on Pega platform side or Identity Provider side, it's a good idea to try the same scenario with only one of these parties involved. You can use Postman to act as OIDC client, so you can use this tool to remove Pega Platform from the equation.

Start Postman, create a new request, and switch to the “Authorization” tab. Choose “OAuth 2.0” as the type. This will give you "Get New Access Token" button, which allows to initiate the OIDC authentication flow.

After clicking "Get New Access Token" you get a configuration dialog. Copy configuration from your Pega authentication service to the corresponding fields in Postman. Notice that the state parameter is not part of the authentication service configuration, but is chosen randomly by Pega Platform for each request. You can see a sample value of the "state" parameter in authorization URL we examined in a previous section. For Postman you can use any random string there.

The screenshot below shows Postman configuration corresponding to the Pega authentication service configured with miniOrange.

Click “Request Token”. This will trigger the authentication process and on successful completion will present you with a token obtained from Identity Provider, without any participation from the Pega platform.

You can now copy the value of the ID token and use JWT Debugger to analyze the contents of the token and verify its signature. As described here, miniOrange provides their key in the PEM format. This is not a problem for JWT debugger, you can use a key in PEM format directly to verify the token signature.

If the OIDC flow executed with Postman succeeded , the token contained the expected information and was verified successfully, yet the integration with Pega does not work, you now that the problem may be misconfiguration on the Pega side. However, if you were able to reproduce the problem with the integration using just Postman, you now know that it has nothing to do with Pega and you should focus your investigation on the Identity Provider.

Appendix: list of software

This article used the following versions of the described software:

Pega Platform Data Integration Security Developer Knowledge Share