Single Sign On – Part 2 – Configure IdP

Finally, its time to document my SSO implementation in Pega personal edition 8.2 using OpenAM. In this article, we will see about setting up the Identity provider using OpenAM.

To know basics about the SAML, IDP, SP (theory 😉) visit my previous post!

I am splitting this post into two main areas

1. Hosting the OpenAM application in Tomcat server.
2. Configuring the IdP details in the OpenAM studio

How to host OpenAM application locally?

Step 1: Download the necessary packages from backstage.forgerock.com

Follow the below link –

https://backstage.forgerock.com/downloads/browse/am/archive/productId:openam/minorVersion:13/version:13.0.0/releaseType:full

Download both the packages – OpenAM13.war and OpenAM13.zip (it will take quite 100s of MB!!), because we will use both at certain point of time!

First, we will start with deploying the war file in our Apache tomcat server.

Step 2: Copy the downloaded war file in the right location –

<Your personal edition directory>/tomcat/webapps.

You should see the other war files – prhelp and prweb

Important note: Make sure you change the name of the downloaded war file and remove the special characters. You just give it as openam or openam13. If you don’t, your deployment will fail!! (my first hurdle)

Step 3: Restart the apache tomcat server. I meant your pega personal edition server.

In the server logs, you should see the successful deployment message.

Step 4: Launch the tomcat manager portal.

http://localhost:8080/

Note: Your port may vary based on your usage!

Click on the manager app. You will be prompted to enter the username, password!!

What is the username, password?!

Get back to the installed pega folder and switch to the below path

<Pega>/tomcat/conf – tomcat-users file

Open the file in notepad ++

Update the tomcat users with the right roles.

I already customized the file by adding the roles ‘manager-gui,admin-gui’ to the user tomcat.

<role rolename=”manager-gui”/>

 <role rolename=”admin-gui”/>

<user username=”tomcat” password=”s3cret” roles=”manager-gui,admin-gui”/>

Note: I removed some unwanted users from the default file. You can either keep it as such or remove it. But do not forget to add the above 3 lines 😊

Once you are done with the update, save the file and restart the server.

Now hit the manager app again and provide the right password.

Step 5: You should see the available list of applications and OpenAM is one of them.

On the right side you will also see the status of the applications. From this page, you can start stop any applications, including the pega prweb application!

Now we have successfully deployed the OpenAM server and the admin console is up and running.

We are done with hosting the OpenAM application in the tomcat server.

Next big step! Its going to be really big!!

How to configure the IdP details in OpenAM application?

Step 1: Setting up default configurations

Step 1.1: Once your OpenAM application is up, hit the below URL – http://localhost:8080/openam

First, you need to set up few default configurations for your OpenAM application.

Step 1.2: Select Create Default Configuration option and accept the license agreement.

You will be prompted to provide credentials for default users – amadmin(the master admin user), URLAccessAgent.

Important note: Make sure, you don’t forget your adAdmin password 😊

Once done, click create configuration.

You will the configuration in process option! You will also note that it starts with installing OpenDJ.

What is OpenDJ?

OpenDJ is a directory server that implements the Lightweight directory access protocol.

Note: we will also create users in the next post

It works in conjunction with OpenAM for the SSO implementations.

So, OpenDJ is a product from ForgeRock. In my previous post for LDAP, I used Apache directory server from Apache. So, this is the right alternate for that!

We won’t  see much of OpenDJ in this post.

Once default configuration is completed, you will see a success message popup.

 Proceed to login and provide the amAdmin credentials.

 Make note of the new folder under your desktop user home, where you will see all the Openam application configuration details.

We will use the above directory location often going forward!

Step 2: Setup a new Realm

Once successfully logged in, you will land up in the homepage of OpenAM.

 You need to start with creating new realm.

What is realm in OpenAM?

You see the description in the homepage as well.

Realm can be created to give a set of users, the same configurations. Same type of authentication.

So basically, you can create a Realm for an organization, or it can be drilled down to department as well

Let’s start with creating a new realm.

Step 2.1: Click on the new realm.

Step 2.2: Provide a meaningful name and parent can start with the top-level realm.

 You will see a new realm on the dashboard.

 Step 2.3: Click on the realm to view the overview.

 Step 3: Create a new Identity Provider

Step 3.1: From the realm overview page, click on the Create SAMLV2 Providers.

Step 3.2: Then click on the ‘Create Hosted Identity Provider’ to create a new IdP.

You will land on the configuration page, to enter the details.

 Step 3.3 – Enter all the configuration details

Do you have metadata for this provider – No (we are going to create the metadata now!)

Realm – Select the new realm we created – MyKnowPega

Name – Typically the URL. Keep it as default – http://localhost:8080/openam.

Signing Key –

 You will see one default key – test.

But it is expired on 2018 :D.  So, hold this page and let’s start to create our own key!!

How to create a new signing key?

This basically involves the below 5 steps

Step 1: Create a new java key store (.jks file) that contain the public and private key. We will use the default java keytool to create our own key.

Navigate to your java JDK – bin folder.

 There you will find the keytool file.

Generating a new key from command line is very easy and you will see lot of google posts on it. Also, an LSA topic 😊

Now open the command line tool – cmd

Change your current directory to bin. If you are not familiar with commands, you can check google. You can also follow the exact commands in the below picture

 Now copy paste the below command with arguments

keytool -genkeypair -alias myknowpega -keyalg RSA -keysize 1024 -validity 730 -storetype JKS -keystore keystore.jks

The highlighted part myknowpega serves as the key alias name

You will be prompted with a series of questions to form the aliases. Fill patiently 😉

 Here also you will be prompted to enter the password. Do not forget it! (I do always!!)

Once everything goes well, you will see a keystore.jks file created in the bin directory.

 Step 2: Make your certificate trusted. (optional steps, but it will be a good learning 😊)

So basically, you need to add this certificate in the java trust store. In the cacerts file. Certifate Authority file.

Step 2.1: export the self-signed certificate.

keytool -exportcert -alias myknowpega -file idfSelfSignedCert.crt -keystore keystore.jks

 Certificate is stored in the current directory.

 Step 2.2: Import the certificate into cacerts file

keytool -importcert -alias myknowpega -file idfSelfSignedCert.crt -trustcacerts -keystore C:jdk1.8.0_121jrelib/security/cacerts

 Important note: The default password for the cacerts keystore is – changeit

You see a successful message Certificate was added to keystore.

Now this certificate can be used by other applications using the same Java run time 😊

Step 3: Generate the encrypted password files

So usually, you will see two password files one for trust store and another for signing key.

We saw the OpenAM provides an expired key – test right. You will see the corresponding .jks file and the two password files in the below folder structure corresponds to openam application data.

C:Userspremgopenamopenam

For our new key – myknowpega, we already created .jks file. We need to create the two password files and replace them with the above files.

The data in the password files, should be encrypted, so we need to use another tool SSO Admin Tool, that comes with the openam zip file we downloaded before

How to use SSOAdminTools to encrypt the password?

Step 1: Unzip the package SSOAdminTools-13.0.0

Note to me: The post is getting dragged to be the biggest post in myknowpega!!

 Step 2: Double click and run the setup bat file.

 Step 3: Accept all the default prompts for path configuration.

 Important note: Sometimes, the command prompt may close automatically when you double click, in such case open a new cmd tool and switch to the folder and then just execute – setup and click enter, you will be guided to the wizard.

Now you will see the new log and debug folders created.

 Step 4: switch inside openam/bin, you will see batch file ampassword.

This is responsible to encrypt password.

Now open the command line tool and switch to the right folder structure using cd command.

 Step 5: Now create two empty files with password values using the below commands

 — echo Password123 >storepass.cleartext

— echo Password123 > keypass.cleartext

The above comments creates a file and put the echo value inside.

 You will see two files were created. You can check the clear text value.

 Now finally we need to encrypt the file.

Important note: Make sure there are no extra leading spaces after the password!!

Step 5: Execute the below comments to encrypt the password value and save the content into new files – .keypass and .storepass

— ampassword -e keypass.cleartext > .keypass

— ampassword -e storepass.cleartext > .storepass

 You will see the new files in the directory.

 We have successfully generated the encrypted password files.

Let’s get back to the old story (jump one loop outside 😉)

Step 4: Copy the new .jks file (we created in step 1) and .keypass and .storepass files to the right application data location.

You can take a backup of the current files and copy paste the right files

.jks (will be in the JDK/bin) and password files are seen in the ampassword location.

 You can cross verify the timestamp. The newly created files are added at the right directory.

Step 5: Now stop, start the openam server from the tomcat manager

http://localhost:8080/manager/html

 Again, let’s jump one loop above to step 3.3 Enter configuration details. We have successfully created a new signing key.

Step 3.3

Signing Key –  BOOM 😀

 You see test key is removed and myknowpega is shown.

New Circle of Trust – Its basically to form a COT with similar applications. Give a new name – MyKnowPega

Attribute Mapping – You can specify the attributes that can be used to map the directory attributes to Pega operator attributes.

For now, I just added uid and telephonenumber.

 Once done, click on the configure on the top right and then finish the configurations.

 Step 4: Prepare the name ID format (this was my biggest hurdle, it took days to understand)

NameID is used by OpenAM to uniquely identify the operator.

By default template, OpenAM supports two way of identification – through email ID and through the unique ID.

Some of the applications use email ID as the user ID for login. In such case, we may need to validate the user ID (email ID) against the email ID of the user record saved in LDAP directory.

In our case, we are going to validate our pega operator ID against the user ID in the LDAP directory.

So, you can remove the default NameID entries for email

Pega doesn’t support the name ID format persistent and transient as well

Supporting article – https://community.pega.com/support/support-articles/saml-response-nameid-not-read-external-saml-response

So you need to remove all these three name ID entries

How to update NameID entries in OpenAM?

Step 1: Click on the federation tab.

You will see the configured CoT and IdP.

Step 2: Click on the IdP link to open the configuration details

Scroll little down to the NameID format.

Step 3: Remove the persistent, transient and emailAddress from the format list (first block)

Step 4: Remove the mail value map and add the uid value.

The NameID value map is the key area you should note down. As I said before, OpenAM gives the first priority to the mail. It sets the value for emailAddress as mail attribute. We are not going to use it, so just remove the attribute 😊

So where to add the uid value map? – Specify the uid value to unspecified (default)

Note: You cannot update the unspecified row. You need to remove the marked one and add a new one with value like below.

Once done with these two changes, click on save

One final step before completing the identity provider configurations.

Step 5: Generate the IdP metadata.

Till now we completed all the configurations, now its time to generate an XML metadata.

This metadata can be imported by the service provider applications to make use of this IdP and come to a common agreement.

Hit the below URL –

http://localhost:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=http://localhost:8080/openam&realm=/MyKnowPega

Based on your port, openam application name and the query string parameter – realm name, change the URL accordingly.

You should not see the removed NameID formats in the generated XML.

Save the XML with some meaningful name in your local machine

I am ending this looong post 😀

In this tutorial, we have successfully launched a new OpenAM application and created a new Identity provider entity.

In the next article. we will see how to configure a service provider in Pega as well in Open AM and test the SSO logging. Only one more hop, join me!