Discussion

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:

  1. {
  2. "keys":[ ]
  3. }

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:

  1. {
  2. "keys": [
  3. {
  4. "kty": "RSA",
  5. "e": "AQAB",
  6. "kid": "CsVfry3eToUyZdOA",
  7. "n": "zIKQ...oAow"
  8. }
  9. ]
  10. }

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:

  1. {
  2. "keys": [
  3. {
  4. "kty": "RSA",
  5. "e": "AQAB",
  6. "kid": "1",
  7. "n": "zIKQ...oAow"
  8. }
  9. ]
  10. }

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.

Comments

Keep up to date on this post and subscribe to comments

February 5, 2019 - 8:04am

Thanks for the article.

Having some issue when trying this, Changed the keystore file extension from jwks to jwk and the issue got resolved.

 

Thanks

Saikat

Pega
February 5, 2019 - 8:30am
Response to Saikatc8

Hi Saikat,

Thank you for pointing this out. I will update the article to use "jwk" extension.

Jarek

February 8, 2019 - 12:38pm

HI Jarek,

Its good article.Can you please also mention do we check anything on the web.xml entry?

Regards,

Anandh

Pega
February 8, 2019 - 1:14pm
Response to AnandhP2

Hi Anandh,

I'm not sure if I understood your question correctly - what do you mean by "the web.xml entry"?

February 8, 2019 - 1:34pm
Response to Jarek.Cora

Hi Jarek,

Do we need to change anything on the <servlet-name> tag, we have the below entry on the web.xml. Do we need to change/update anything.

<servlet>

<servlet-name>PRAuth</servlet-name>

<display-name>PRAuth</display-name>

<description>PRAuth</description>

<servlet-class>com.pega.pegarules.internal.web.servlet.WebStandardBoot</servlet-class>

<init-param>

<param-name>PegaEtierClass</param-name>

<!-- COMPONENTS: This was previously com.pega.pegarules.services.HttpAPI -->

<param-value>com.pega.pegarules.session.internal.engineinterface.service.HttpAPI</param-value>

</init-param>

<init-param>

<param-name>AuthenticationType</param-name>

<param-value>PegaAuthentication</param-value>

</init-param>

<init-param>

<param-name>StatusPage</param-name>

<param-value>/diagnostic/status.jsp</param-value>

</init-param>

<init-param>

<param-name>RuntimeServletName</param-name>

<param-value>PRAuth</param-value>

</init-param>

<init-param>

<param-name>SecureServletName</param-name>

<param-value>PRAuth</param-value>

</init-param>

</servlet>

 

Regards,

Anandh

 

Pega
February 8, 2019 - 2:13pm
Response to AnandhP2

Hi Anandh,

No, you don't need to change anything in web.xml of your Pega server. The only thing that is required is that your server is accessible via HTTPS, not just HTTP. Also keep in mind that I tested this functionality with Pega 8.x (aka Pega Infinity). Earlier versions, such as Pega 7.x,  may require additional, manual configuration.

February 8, 2019 - 3:03pm
Response to Jarek.Cora

Thanks Jarek, we are trying in 7.4 and its not redirecting into the "Authorization endpoint" which i mention on the rule.

Windows authentication its not happening, can i enable any logger to troubleshoot?

Regards,

Anandh

Pega
February 12, 2019 - 5:05am
Response to AnandhP2

Hi Anandh,

In Pega 7.4.1, I set logging level to ALL for "com.pega.pegarules.integration.engine.internal.sso.oidc.OIDCClientHandler " and I can see the following entry in the log file:

(sso.oidc.OIDCClientHandler) DEBUG  - Constructed authorization URL for OIDC provider : https://....

It contains the URL to the external Identity Provider configured for my authentication service.  Please enable the above logger to see if the URL is the one you expect.  Also please make sure you start the whole login by going to the Login URL specified by your Authentication Service, not to any other servlet or login page provided by Pega.

February 12, 2019 - 10:52pm
Response to Jarek.Cora

Hi Jarek,

We have 7.4 system, will this work on this version also we have RS256 algorithm on the metedata. Will Pega support those algorithm? 

Regards,

Anandh

Pega
February 13, 2019 - 4:57am
Response to AnandhP2

Hi Anandh,

I haven't tried it on 7.4 personally,  but I believe it will work because full support for OpenID Connect was introduced in 7.4. Yes, Pega supports JWT tokens signed with RS256 algorithm.

Jarek

February 10, 2019 - 9:06am

Hi @Jarek

Would this work with Pega 7.4? Specifically, with Pega 7.4 on Openshift? Is there a way to troubleshoot this configuration when the Login URL does not redirect to the IDP for authentication?

Balaji

Pega
February 12, 2019 - 4:05am
Response to BalajiR1491

Hi Balaji,

I tried OIDC configuration with Pega 7.4.1 (Build: PRPC-7.4.1-281). It worked correctly, in particular redirection to the Identity Provider login page happened as expected. I guess it's obvious, but make sure that you start the whole login process by going to the Login URL specified in your Authentication Service, which has the form:  https://YOUR_HOST/prweb/PRAuth/SERVICE_ALIAS  This should redirect the browser to the external Identity Provider login page. If this doesn't happen I would suggest trying to make this request with a tool which allows to trace HTTP requests and responses, such as Postman or wget.