Authenticating to Pega with Auth0 using OIDC protocol
This article describes how to configure Pega Platform to authenticate end-users against Auth0 using OpenID Connect (OIDC) protocol.
The solution has been verified with Pega Platform 8.1 and 8.2.1
Step 1: Define application in Auth0
Login to the Auth0 management console available at https://manage.auth0.com and create a new Application that will represent integration with Pega Platform. Choose a name, for example Pega and "Regular web application" as the application type. Click "Create".
On the next screen choose the "Settings" tab note the value of the domain field, just below the application name. In our example it is pegadev.eu.auth0.com.
Metadata describing the OpenID Connect configuration is published at the URL created by appending /.well-known/openid-configuration path to the domain URL, so in our example it is https://pegadev.eu.auth0.com/.well-known/openid-configuration
Verify this URL works for your domain and returns a non-empty JSON file.
Step 2: Create Authentication Service in Pega Platform
Login to Dev Studio of your Pega instance to create a new Authentication Service that will represent integration with Auth0. In order to do so, click Configure > Org & Security > Authentication > Create Authentication Service. Choose “OpenID Connect” as the type, fill in other fields and click “Create and open”.
On the next screen give the service an alias, for example "Auth0", and click “Import metadata” to import the configuration from the URL you gathered in the previous step. This will fill-in the "OpenID Connect provider configuration" section.
Now you need to specify the name of OAuth claim that will be used to map users authenticated in Auth0 to Pega operators. See here for more information about operator mapping, as this is not specific to Auth0. Just remember that any operator which is expected to authenticate with Auth0 must have “Use external authentication” option enabled.
Step 3: Reconcile configuration between Auth0 and Pega Platform
In this step you need to:
- Copy Client ID and Client Secret from Auth0 application to Authentication Service
- Copy Redirect URI from Authentication Service to Auth0 application
- Ensure sure that the "Token Endpoint Authentication Scheme" setting in Auth0 application matches the "Client authentication scheme" in Authentication Service. The recommended way to do so is to set "Token Endpoint Authentication Scheme" to POST, which is the default setting in Authentication Service.
Step 4: Verify the configuration
Make sure you have a user defined in Auth0, which can be mapped to Pega operator in accordance with the mapping you defined. Point your browser to the URL specified in the Authentication Service as "Login URL". You should be redirected to the Auth0 login screen, and after authenticating redirected back to Pega Platform, successfully logged in to Pega application.
Troubleshooting
In case of any problems with the integration, refer to Troubleshooting OpenID Connect (OIDC) integrations article.