Authenticating to Pega with miniOrange using OIDC protocol
This article describes how to configure Pega to authenticate users against miniOrange using OpenID Connect protocol. From the protocol perspective, in this setup Pega Platform acts as the OpenID Client and miniOrange acts as OpenID Identity Provider.
The solution has been tested with Pega Platform 8.1.1 and miniOrange in Cloud trial version.
Step One: Create Authentication Service in Pega
In the Dev Studio of your Pega instance 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, type-in the service alias (1) and note the value of the "Redirect URI" field (2). You will need this URI in the next step.
Step Two: Create miniOrange application
Login to miniOrange console and create a new application of "OpenID Connect" type.
Specify the Client name (Pega) and the Redirect URI. This must match the "Redirect URI" field from Pega authentication service (the one you noted in the previous step)
Finally associate an authentication policy with your application. For the purpose of this article we created a new policy named "Simple Password Policy" and associated it with the DEFAULT user group and the Pega application.
Step Three: Reconcile configuration of miniOrange and Pega
In this step you need to copy configuration of miniOrange application to the Pega authentication service. At the moment miniOrange does not provide discovery endpoints for applications, so you cannot use "Import Metadata" feature to automatically configure the authentication service. Instead you need to manually copy the following values:
- Authorization Endpoint (3)
- Token Endpoint (4)
- User Info Endpoint (5)
- Client Id and Client Secret (6)
The values need to be entered into the corresponding fields of the authentication service:
Additionally you need to specify the name of OAuth claim that will be used to map users authenticated in miniOrange to Pega operators. The claim name must be specified in curly braces. Typically email is used for that purpose.
Step Four: Import public key for validating tokens
OpenID Connect specification requires the Client (Pega in our case) to verify the signature of each ID token received from Identity Provider. In order to do so, Pega must know this provider's public key, therefore the keystore with this key must be included in the authentication service configuration.
miniOrange provides application-specific public key in the PAM format. You can download it from the link marked "Certificate" on the list of applications in your miniOrange console.
After downloading the key, you need to add it to a keystore in a format supported by Pega. For the purpose of this article we will use JSON Web Key Set (JWKS) format for the keystore. There are two options to create a JWKS keystore from a PEM key. You can do it using either a command-line tool, or an online tool and text-editor.
Option 1: Command line tool
The simplest way is to use node-jose-tools toolkit. It is a front-end to node-jose library, which is an implementation of JSON Object Signing and Encryption (JOSE) specification. After installing the toolkit, run the following command:
jose addkey --create --beauty RSA256_OpenID_public_key.pem > moas-openid.jwk
where RSA256_OpenID_public_key.pem is the "Certificate" you downloaded from miniOrange.
Option 2: Online tool
You can use JWK to PEM Convertor online to convert the key from PAM to JWK format. To do so choose "PEM-to-JWK" option, paste the key in PAM format and click submit. You will get a JWK key, which you now need to add to a JWKS keystore.
To do so, simply create a text file with the following contents:
- "keys":[ ]
Then paste they JWK key between [ and ] characters and save the file as moas-openid.jwk.
Regardless of which option you chose, you should now have a JWKS keystore in moas-openid.jwk file, which should look like this:
- "keys": [
- "kty": "RSA",
- "e": "AQAB",
- "kid": "CsVfry3eToUyZdOA",
- "n": "zIKQ...oAow"
As you can see there is one element in the keys array, which corresponds to the public key from miniOrange. This key is described by four properties. Three of them came from the PEM file. These are the key type ("kty"), exponent ("e") and modulus ("n"). The fourth one, that is the unique identifier of the key ("kid"), was not originally present in the PEM file and was randomly generated during conversion from PEM to JWK format.
However, each ID token specifies the unique identifier of the key that should be used to verify its signature. In case of ID token issued by miniOrange, this identifier is always equal to "1". Therefore you need to modify, with a text editor, the kid of miniOrange key in your keystore to be equal "1", to match the kid which comes with minOrange tokens. So the final keystore in moas-openid.jwk file should look like this:
- "keys": [
- "kty": "RSA",
- "e": "AQAB",
- "kid": "1",
- "n": "zIKQ...oAow"
Now you need to import they keystore to Pega. In the DevStudio click Create > Security > Keystore, fill in the fields, and click "Create and open".
On the next screen choose "Upload file" as the keystore location, JWK as the keystore type, upload your moas-openid.jwk file and save the keystore.
Go back to the authentication service configuration and fill-in the "ID token processing" section. Specify https://auth.miniorange.com as the "Issuer" and your newly created keystore as the "Signature truststore".
Save the authentication service.
Step Five: Test the authentication experience
Now you need to create a test user in miniOrange and a corresponding operator in Pega. If you chose email as the basis of mapping users to operators, then the email of miniOrange user must match the name of operator in Pega. Additionally make sure that the operator in Pega has "Use external authentication" option checked.
Start a new incognito window of your web browser (to make sure you are not logged in) and go to the URL specified in the authentication service as "Login URL". You will get redirected to miniOrange for authentication. Enter username and password of the test user. Upon successful authentication, you will be redirected to Pega logged in as the operator corresponding to the test user.
Keep up to date on this post and subscribe to comments
- Authenticating to Pega with miniOrange using SAML protocol
- Authenticating to Pega with Auth0 using OIDC protocol
- Authenticating to Pega with Auth0 using SAML protocol
- SAML SSO: Error Message: Unable to process the SAML Web SSO request: Unable to process SAML2 Authentication response: Caught Exception while validating SAML2 Authentication response protocol: NULL
- Unable to process the SAML WebSSO request: Unable to process SAML2 Authentication response: Caught Exception while validating SAML2 Authentication response protocol: Caught Exception while creating Keystore instance