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:

  1. Initiating OIDC flow
  2. Constructing authorization URL for OIDC provider
  3. Constructed authorization URL for OIDC provider : https://dev-500306.oktapreview.com/oauth2/...
  4. Processing authcode received from OIDC provider
  5. Fetching access token using authCode received
  6. Successfully fetched access token and ID token using authCode
  7. Validating ID token received from access token end point eyJraWQiOiJ5dVBUeVBUUEdjcE1WamxpNE...
  8. Successfully validated ID token with standard claims
  9. Retrieving userInfo claims from user info Endpoint
  10. Fetch operator from claim {email} from received ID token claims
  11. Successfully established operator from received ID token claims
  12. 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:


Keep up to date on this post and subscribe to comments

February 9, 2019 - 4:27pm

Hi @jarek

Do these settings work on Pega 7.4 running inside Openshift? I have configured the log level as you had indicated. I have also configured the Authenticator service to connect using OpenID. However, I see the message in the PegaRULES-ALERT.log as "Error authenticating xxxxx: The user must use external authentication". Can you tell me how to troubleshoot the issue?



February 11, 2019 - 5:52am
Response to BalajiR1491

Hi Balaji,

Each Pega user (aka operator) which logs in via OpenID must be configured on the Pega side to use external authentication. If you go to the operator record in Pega Designer Studio, and click "Security" tab, you will see a checkbox labeled "Use external authentication". This must be checked to allow the operator to log in via OpenId.


February 11, 2019 - 8:13am
Response to Jarek.Cora

@Jarek, Thanks for the reply. I have configured the operator id to have external authentication. But, still I get the above error. (Error authenticating xxxx: This user must use external authentication) How do I troubleshoot this issue?

February 12, 2019 - 3:09am

Hi Balaji,

I looked further into this problem.  The message  "Error authenticating  [UserName]: This user must use external authentication." is logged in case a user with external authentication checkbox checked is trying to log-in using Pega authentication.  This would suggest, that your operator is properly configured, but you try to login in via Pega, instead of external identity provider.  

Can you confirm that when you log in, you enter the credentials on a login page served by external OpenID provider, not on any page or servlet served by Pega? 

February 12, 2019 - 9:44am
Response to Jarek.Cora


I am not able to get the login page of the external IDP when I try to hit the login URL configured in the Pega authenticator service. I am suspecting the integration with IDP is not configured correctly. I am following up with the IDP. I will post back with my comments. Thanks!

February 12, 2019 - 10:10am
Response to BalajiR1491

Hi @BalajiR1491

Yes, with properly configured integration going to Login URL should redirect you to Identity provider login page. 

You may try to set logging level to ALL for "com.pega.pegarules.integration.engine.internal.sso.oidc.OIDCClientHandler " and look into the log file. There should be a message "Constructed authorization URL for OIDC provider" followed by the URL to which Pega redirects when you acess the Login URL. This may help you with troubleshooting.

February 14, 2019 - 12:33pm
Response to Jarek.Cora


I configured the Authentication service to be similar to your definition above but I did not get redirected to the IDP login screen. Instead, I only get the Pega login screen. However, I was able to generate an access token using postman client. Also, even with the log levels configured in Pega, I did not see any entries in the PegaRULES.log relating to the OIDC connect authentication. We are working with the beta version of Pega 7.4 running inside Docker container. I am guessing that the Docker image does not have the PRAuth modules relating to the OIDC Connect. I will contact Pega if they have any updates. Thanks!

February 28, 2019 - 8:32am
Response to BalajiR1491

Please check your web.xml and see if PRAuth is one of the servlet defined. I am suspecting you are using a prweb from a older release.

February 28, 2019 - 12:46am

Hi I'm working on OIDC integration with Pega 8.1.1.

At Authentication Service in DEV STUDIO, OIDC Auth Service does not provide Authentication Activity and Timeout Activity. I need to imprement timeout mechanizm with OIDC. What is the extention point for timeout with OIDC as SSO providor?

February 28, 2019 - 5:33am
Response to tamont52


At the bottom of OIDC Authentication Service configuration, in the Advanced section, there is a checkbox which allows you to  make the service respect the authentication timeout specified in the operator's access group.

February 28, 2019 - 7:14am
Response to Jarek.Cora


I already knew "Use access group timeout" and it corresponds Data-Admin-AuthService.pySupportsPegaTimeout to "true".

but when i login to pega through OIDC, nothing occurs nevertheless Authentication Timeout specified in AccessGroup settings. Of course non-SSO authenticated operator belongs to same AccessGroup can recieved re-login attempt dialog.

February 28, 2019 - 7:54am
Response to tamont52

Tamon, I will ask some of my colleagues with more knowledge on the subject to take a look at your question.


February 28, 2019 - 8:33am
Response to tamont52

The access group timeout is the inactivity timeout. There are no hooks for timeout activity for OIDC. Can you describe what you expect to happen upon timeout?

March 1, 2019 - 2:32am
Response to Srikanth

Hi Srikanth

Thank you for your relply.

When thinking about SSO, once Pega as RP apps kill an operator's requestor after timeout, then the operator try to access to pega and the operator redirected to IDP. IDP comfirms the request still be authenticated it self because IDP's session remains. so, the operator can re-login to pega without any challenges held by IDP. this makes loop that RP kills its session, then IDP allow to login to RP, then RP kills its session and so on. To end this loop, i must imprement kill IDP's session by timeout within RP's session. Thus i need to hook timeout.

In particular, after timeout in Pega(RP) i have to make browser redirected to call end_session_endpoint to IDP for killing IDP's session. ("end_session_endpoint" is specified OpenID connect spec at  "https://openid.net/specs/openid-connect-session-1_0.html#RPLogout".)

Tentatively I've implemented setting Authentication Timeout Activity to OIDC Authentication Service(Data-Admin-AuthService) and it enabled to  hook authentication timeout with SSO operator.
but as you mentioned OIDC does not provide functionality to setting "Authentication Timeout Activity(.pyTimeoutActivity)". So this way is not garanteed by anything  else. What is the correct way?

My corregue asked about this at SR-C80960. 

June 12, 2019 - 11:54am

Hi @Jarek.Cora

We have an application which going to accessible over Web and mobile app. If I can configure the authentication service rule based on the link https://community1.pega.com/community/pega-support/question/configuring-pega-mobile-client-authenticate-against-okta , can I leverage it for both Web & Mobile. In that article, in step 1, I see that in the Okta console there is an option to choose the platform and its either one of mobile or web.  How can this be made to work for both web and mobile.

And unlike SAML, I don't see any activity in the authentication service rule which is called post authentication, in which we can any further details to the operator ID. Is there any such provision in Open ID connect



June 13, 2019 - 2:04am

Hi Venkat,


Thank you for your questions. The configuration described in https://community1.pega.com/community/pega-support/question/configuring-pega-mobile-client-authenticate-against-okta will work for both web and mobile. The fact that we choose "native" type of integration in Okta console does not prevent it from working in web. In fact Step 4 in Part One of this article describes testing this setup with a desktop browser.

As for post-auth activity, this should work with OIDC. However, since Pega 8.2, operator provisioning supports DataTransform , so in many cases there is no longer need to use  post-auth activity.