OpenID Connect Authentication Service in Pega

December 10, 2024 Code Vault Curators

This is the continuation of the previous blog article on OpenID connect basics. It is mandatory to go through the below article before proceeding.

OpenID Connect Understanding

In this tutorial, we are going to create a new OpenID Connect authentication service in Pega using Google as the OpenID Identity provider.

Pega supports only the authorization code OpenID flow. As a recap below is the process flow and steps involved in OpenID connect flow.

Note: OpenID authentication service is supported from Pega 7.4 & + versions

Step 1: The end user opens the Pega application and trying to login, initiate the request using Google sign-in.

Step 2: Pega, the relying app sends the authentication request to Google, the OpenID Identity provider.

Step 3: Google, the Identity provider presents the user with a screen to enter the login credentials and the credentials are submitted to the Identity provider.

Step 4: With regards to authorization code flow, the authorization code is generated and sent to the relying app.

Step 5: With the received authorization code, the relying app Pega sends a token request to the identity provider and receives the token (access token and ID token)

Step 6: With the ID token, the relying app sends a request and retrieves the user info necessary for authentication.

In the previous post, we already created a Google developer application. We will be using the same application and its credentials in this tutorial.

How to create a new OpenID connect authentication service?

The steps are similar to the LDAP/SSO authentication service creation.

Important note: make sure you use https url.

For the personal edition, follow the link to host your personal in https.

Step 1: Designer studio -> Org & Security -> Authentication -> Authentication service

Click create and open

Step 2: Provide the URL information

I am going to name the authentication service alias as “GoogleAuth”

So my login URL will be https://localhost:8443/prweb/PRAuth/GoogleAuth

Step 3: Provide the OpenID connect provider configuration

For Google, I am not able to get the metadata to fill the form automatically, instead you can fill it manually.

Authentication flow – Prefilled as Authorization Code and is read-only and the only option.

Authorization endpoint – https://accounts.google.com/o/oauth2/auth

Token endpoint – https://www.googleapis.com/oauth2/v3/token

Userinfo endpoint – https://www.googleapis.com/oauth2/v3/userinfo

Logout endpoint – you can leave it empty for now

This is again a three-legged flow as we saw in the OpenID basics post. At the end we need to get the User info details using the id_token.

Redirect URI – Pega fills automatically to https://localhost:8443/prweb/PRAuth

Important note: At the end of this rule configuration, we need to update this Redirect URI in the google developer console application.

Step 4: Provide the ID token processing details

To process the ID token (validate), we need the public key of the identity provider.

We know that the keystore rule is used to store the public keys/certificates in Pega.

Step 4.1: Create a new keystore instance to save the Google public key.

Records -> Security -> Keystore -> Create new

Step 4.2: Use the reference to URL option to get the JWK.

In the keystore location picklist, select Reference to URL.

Keystore URL – https://www.googleapis.com/oauth2/v3/certs

Keystore type – JSON web key

Step 4.3: Save the keystore instance. You should be successfully saving the keystore without any error. If no error, it means, your key is successfully saved with the keystore instance 😊

Important note: Pega hits the https URL – https://www.googleapis.com/oauth2/v3/certs to get the key, so make sure your internet connection is up!!

After creating a keystore instance, get back to the authentication service rule and update the ID token processing block

Issue – accounts.google.com

Step 5: Provide the client information details

In the last post, we created a Google application in developer console and saved the client credentials.

Provide the same in the client ID and secret.

Scope – add the profile and email scope along with the default OpenID.

The scope is used to get the OpenID claim data (user info data)

Step 6: Provide the Operator identification details

Map operator ID from claim – email.

Note: claim here refers to the user info detail and I am going to use the email to identify my pega operator ID.

Also, additional provisioning is made so that if the operator is not found in the system, then a new operator ID is created on the fly.

I used my operator as the model operator.

In the advanced configurations, you can specify how to send the authentication code and the access token. Keep the default configuration as such as google identity provider.

Save the rule.

Remember to update the redirect URI in the google developer application.

Step 1: Open the google developer console, switch to your project and click on the credentials.

Step 2: Update the redirect URI

Scroll down and update the value – https://localhost:8443/prweb/PRAuth

Now we are ready for testing 😊

How to test or debug the OpenID Connect authentication mechanism?

Step 1: Sign out of all your pega sessions and hit the OpenID Connect login URL for google

https://localhost:8443/prweb/PRAuth/GoogleAuth

You will be redirected to OAuth sign for your client ID.

I am using pegaknowledgesharing@gmail.com to login

Step 2: Make a note on the URL header.

Step 3: Successfully logged in Pega.

Check your operator records.

You see a new operator ID is created for pegaknowledgesharing@gmail.com

Open and check the operator record. This is the exact copy of my model operator “Prem”

Happy that OpenID connect worked on the very first attempt 😁

How to debug OpenID Connect in Pega?

We saw in the previous post that id_token we get from the identity providers contains the secured client details (nonce and hash key of access token) in encoded format. It is in JWT format. https://jwt.io/ is used to decode the JWT token.

For this we need the JWT token right? let’s get it first.

Step 1: Set the logger for OIDCClientHandler (OIDC – Open ID Connect)

Designer studio -> System -> Operations -> Logs