This is the continuation of the previous blog article on OpenID connect basics. It is mandatory to go through the below article before proceeding.
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
Click on logger level settings and search for OIDCClientHandler.
Set the level to debug.
Step 2: Sign out pega and Google signin. Try to hit the URL again
https://localhost:8443/prweb/PRAuth/GoogleAuth
Step 3: Open the PegaRULES.log to check the debug entries
Note: for personal edition, following the path to access the PegaRULES.log
Tomcat/work/Catalina/localhost/prweb
Open the log file in Notepad
You see all the steps involved in the OpenID Connect authentication.
You see, Pega validates the ID token. Copy the ID token.
Step 4: Use https://jwt.io/ and debug the ID token
Copy the encoded ID token and check the decoded payload data.
You see the email ID.
You can scroll down to verify the public certificate as well.
Some interesting Pega videos on troubleshooting OpenID connect.
Please visit the link, worth it – https://community.pega.com/video-library/troubleshooting-openid-connect-authentication-service-integration-issues-pega
So hereby we have successfully configured the OpenID Connect authentication mechanism in Pega.
