SAML SSO Authentication service – Connect to Azure Active Directory

In this blog article, we will see how Pega operators can be authenticated against the Azure active directory.

This tutorial was implemented using Pega personal edition 8.5, but the core concepts remain the same in higher versions as well

What is Azure Active directory?

– It is an enterprise identity service provided by Microsoft Azure Cloud.

– It provides single sign-on (SSO) and multifactor authentication features.

Just like any traditional LDAP directory, you can organize the users under groups and provide the right authentication and authorization.

There is another service called Active Directory.

What is the main difference between Active Directory and Azure Active Directory?

Both are more or less the same with Azure active directory providing Identity as a service (IDaaS) solution on the cloud, whereas active directory service is mostly offered on-premise.

You can see detailed differences in the below link

https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-compare-azure-ad-to-ad

If you think of any organization, they might have a subscription from Microsoft – Mostly for using Office365 also other cloud services.

For example- I work in a company that uses Microsoft services, then my email ID – abc@org.com will be registered in the Microsoft active directory and I verify my credentials against the AD to access my office-related tasks, emails, etc. Some 5-10 years before, most of the organizations run their services on-premise. Slowly cloud started gathering over the head of organizations :D.

Now there are lots of cloud solution providers on the Market like

• Microsoft Azure
• Amazon Web Services (AWS)
• Google Cloud Platform (GCP)
• IBM cloud

Why cloud computing?

There are a number of advantages to using cloud computing. Just google – Why do we need to move to Cloud? you will get enough answers :).

I will explain one such advantage.

Let’s say organization ABC does not use cloud computing and run their apps on-premise.

In real-time, you know how much effort in setting up a new infra? – There may be multiple teams between, multiple approvals, we need to request for each component and set up the right infra, set up the networks, and we need to manage the storage space for the apps, request databases, lots and lots of work. We may end up spending time and resources on this infra management.

What cloud computing provides is they offload some of our work – Infrastructure management ( IaaS), platform management (PaaS), and even service management (SaaS). So, in this way, we can concentrate more on building apps and leave the Infra management part to the cloud providers.

We also pay only for what we use and it really contributes a lot in allocating budgets for your applications.

Let’s say the organization started embracing the Microsoft Azure cloud offerings. We need to set up a new Pega application and as a first step, all Pega authentication should be secured via Azure Active Directory and single sign-on should be enabled.

Below is the high-level SAML flow.

Let’s see the steps involved  –

Step 1: The user from a browser session initiates the login request by accessing the login URL.

Step 2: Pega, the service provider, based on the auth service configuration creates an Auth request to the Identity provider – In our case, it is Azure Active Directory

This is the perfect example of SP (service provider) initiated SAML flow. At the end of this post, we will also so IdP initiated SAML flow. Wait for it 🙂

Step 3: Browser relays the SAML request to IdP.

Step 4: In the IdP redirected URL, the user will be asked to enter the credentials for the account he/she tries to log in to. The IdP asserts the credentials and sends the SAML response with the claims data.

Step 5: Browser then relays the response back to Pega, the service provider.

Step 6: With the right auth service processing, the user should be able to access requested resources.

Let’s start with the configurations.

What are the prerequisites for this tutorial?

As a pre-requisite, you need two things

1. A Valid Azure subscription

You can use the free subscription for a month (you need to provide credit card details!!, but will be charged only when you cross a certain limit and you can have control over that).

https://azure.microsoft.com/en-in/free/

There you can use Azure active directory free service.

If you registered for training, you may have Azure pass subscription which you can use as well.

You definitely need a subscription before proceeding.

2. Expose your local personal edition to the internet

In my previous post, I explained how you can freely expose your webserver to the internet using ngrok. Please follow the steps and get it done.

 The main reason is in a few places it was mentioned to use https and there are some localhost exceptions.

https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url

https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url#localhost-exceptions

Pre-requisites are ready!

What are the steps involved in setting up SAML SSO using Azure AD (Entra ID) as the Identity Provider?

Step 1: Create a new SAML authentication service in Pega to get the Service provider details

Step 1.1: Login into https ngrok URL. In my case – https://5b5a115c6dd0.ngrok.io/prweb

Step 1.2: Create a SAML authentication service

Navigate to configure -> Org & Security -> Authentication -> Create Authentication Service

Use authentication type as SAML.

Once created, scroll down, you will see the Service provider details. We will use it in configuring Azure AD.

Note: SP ID can also be created from Azure AD and the same ID can be used here later!

One important thing is you need to disable request signing.

Because we will not enforce signed requests from applications to Azure AD. If you need to sign, then you have to specify the signing and decryption certificates.

Step 2: Enable single sign-on in Azure AD service

Step 2.1: Launch the Azure portal – https://portal.azure.com/#home

Azure portal is like a marketplace where you can purchase and configure your resources from Azure.

I logged in with my personal ID with a subscription pass.

Step 2.2: Open the Azure Active Directory service.

Tenant – It is the organization that owns the service.

Every directory can have only one tenant.

Since I am using my personal email account, I have the default directory as shown below.

You see you also have an option to add your own tenant.

I am going to create a new tenant – MyKnowPega

Step 2.3: Create a new tenant – MyKnowPega (Optional)

Now I am into MyKnowPega organization as shown below.

In the left panel you will see lot of useful configurations to manage and monitor the active directory service.

Step 3: Register application(s)

Step 3.1: In the left panel, under manage, click the Enterprise applications tab.

There you will list of applications registered under the current organization.

Step 3.2: You can click to add new application.

Step 3.3: Use existing Pega application component.

Azure already has an integration Azure AD component to Pegasystems. Just search and select the pega component.

Click the result and then click the Create button on the right

You can also change the name of the application. I am just keeping it as such for now.

Pega application is added to the organization apps.

Step 4: Set up single sign-on.

On the application overview, you will see different options to start with.  Choose setting up single sign-on.

Step 4.1: Select the single sign-on method – Click SAML.

You will see five step configurations to complete the setup

Basic SAML configuration

Identifier  (Entity ID) – Enter the SP identifier URL copying from the pega authentication service rule.

Assertion Consumer service URL – Enter the ACS location URL copying from the pega authentication service rule.

Important note: The service provider ID, here and in pega auth service should match.

Click save.

There is an important configuration – relay state. I am keeping it empty for now. Will come back to it at the end of the post. As a sneak peak, it is related to SP initiated vs IdP initiated SAML flow.

User attributes and claims –

Here you will see the information data that the identity provider (Azure AD) sends in the SAML response. These are the essentials claims and attributes you need to map to the Pega operator record.

I am going to edit and add phonenumber to the response.

Click Edit and then Add a new claim.

Note: You will see all the claims are with namespace – http://schemas.xmlsoap.org/ws/2005/05/identity/claims

Namespaces are usually used to group the claims. For phonenumber we will stick to same namespace.

Source attribute – select user.telephonenumber

You can also use conditions to determine when to send this claim data in response.

Click Save.

SAML signing certificate –

Here you can download the federation metadata.

Click download.

We will now switch to pega auth service to import the metadata.

Step 5: Import IdP meta data

In the IdP information, click on import metadata and upload the file.

You will see all the IdP details are automatically filled from the metadata.

Pega also created the keystore rule from the verification certificates in metadata.

Note: Instead of uploading metadata, you can also download the certificates and provide the IdP URL details manually from steps 3 & 4.

If you are interested, you can open the metadata file and view the content.  You will see all these details.

Step 6: Finish the configuration in pega auth service.

Step 6.1: Specify the alias name for the Auth service – AzureAD

Step 6.2: Operator Identification –

This should be the unique ID. I am going to use the claim data email address.

Note: You can also use the Name identifier in the subject to accept the default Azure AD ID.

To get the claim detail for email, you can click edit in User attributes and claims and get the email claim data .

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Specify the claim name under curly braces

Step 6.3: Enable operator provisioning.

if the operator does not exist in system, then we can provision to create new operator ID.

I use my operator as the model operator.

Step 6.4: Specify operator attributes mapping.

Currently I am mapping email address, phone number, first name and last name from the claims data.

Save the instance.

It is time to test!

But before, we will see if we need to add some users to the application so that we provide secured and restricted access.

Step 7: Add users to the application.

As a first step, you need to some users to your organization and those users can only be added to applications

In the Azure AD left panel -> User -> Add new user

Here you can either create a new user or invite a user via email.

I am going to create a new user.

In the identity I provide the username and password for the user –

User name – Thor@myknowpega.onmicrosoft.com

Click create. You can edit the details at any time.

 I added phone number and email address.

Save the user. Now the user is added to the organization. You need to permit this user to login to the pega application.

In the left panel -> Enterprise applications ->  Pega application

Click and open the application

Get started with assigning users and groups.

Click Add user –

You can add a list of users who are part of the organization into applications.

Add Thor to the application.

Note: you cannot create a group in a free plan.

Click Assign. You should see the user under the application.

Get ready to test.

Launch the auth service URL – https://5b5a115c6dd0.ngrok.io/prweb/PRAuth/AzureAD

You should be successfully redirected.

Enter the right password.

You should be redirected to App explorer after successful login.

You should see the new operator is provisioned in Pega  using model operator and mapping 🙂

We have successfully implemented single sign-on in pega using Microsoft credentials!

Let’s see how to debug this SAML request and response.

How to debug SAML?

There is an interesting Google Chrome extension – SAML tracer, where you will get the SAML details on the HTTP requests.

Just download the extension in your Chrome browser.

Open the extension, this will pop up a window which looks like normal network tracer.

Now try to log in again with the SSO URL. You will see two blocks of SAML tracer entries. One for SAML request and the other for SAML response.

First, let’s check the SAML response.  In the Assertion consumer service line, you will see the SAML response details for each attribute like given name, surname, email address, etc.

All looks good. We will check the SAML request parameters.

You see a property RelayState with some generated ID.

We saw in the SAML flow diagram, messages getting relayed from IdP to SP, SP to IdP via browsers.

There are two types of SAML flow

SP Initiated and IdP initiated.

Till now whatever we saw is SP initiated. We hit the Pega (SP) URL and SP initiates the SAML request. This is basically the normal way of authentication, where users launch the pega URL for login.

What is the role of RelayState in SP-initiated flow?

It is a unique identifier that is sent along the SAML request and passed back without any modification back to the SP.

What is IdP-initiated SAML flow?

I will show you a real time example.

Open the Azure portal and move to the Single sign-on configuration for our enterprise app.

We will finish the fifth step to test the SAML flow from Azure portal (Idp side)

Click test.

Note: you may need to install my apps secure sign in chrome extension to sign in as someone else securely in a new tab.

Click sign in as someone else. By this option, we are initiating IdP initiated flow. Here the first line of request doesn’t come from the pega application, SP. Instead, IdP initiates and asserts the login and calls the assertion consumer service on the SP side.

I am going to log in as Thor.

500 ERROR!!!!

On debugging, in the Pega logs, I can find this run time exception – Missing RelayState information in IDP response.

What is the role of RelayState in IdP-initiated flow?

It is used to redirect the user to the target resource URL. It is mandatory to provide the URL in RelayState parameter.

Specify the URL in Azure active directory service.

In the basic SAML configuration, I am specifying the RelayState value.

Save the instance and try to test again to initiate the IdP initiated flow.

Now you should see a successful login with no errors.

Also on the tracer, you should see the RelayState holding the URL.

Pega validates this RelayState and it should be of URL format with a leading protocol.

Huh.. We are at the end of this post!

As a summary

– In the Azure portal, Azure active directory service, we created a new tenant (organization).

– Under the tenant we added the user to the organization.

– We added an enterprise application for the tenant.

– In the enterprise application we set up the single sign-on using Azure AD. We added claims and downloaded the metadata.

– In Pega, we created an SAML 2.0 authentication service and uploaded the IdP metadata and configured the identification and claims mapping data.

– We made sure that the Identifier in SP details in auth service matches with the Azure AD registration ID.

– We added users to the application in Azure Active Directory.

– For debugging, we used Chrome extension – SAML Tracer.

– We found RelayState holds the identifier for SP initiated SAML flow and for IdP initiated SAML flow it holds the URL.

Hope you all like this article.