SSO in Pega using OpenID (Part 3: Azure AD/ Outlook Account)
In this post let us learn how to integrate Pega with Azure Active Directory (Azure AD). This integration enables the users to be automatically signed in to Pega environment (SSO) using their Azure AD / Microsoft / Outlook account.
To configure the Azure AD integration with Pega, we need to have an Azure AD Subscription. If you don't have an Azure AD environment, you can sign up for a one-month trial.
Add Pega Systems from the gallery
To set up the integration of Pega Systems into Azure AD, you need to add Pega Systems from the gallery to your list of managed apps.
1. In the Azure portal, in the left pane, select Azure Active Directory.
2. Go to Enterprise applications > All applications.
3. To add an application, select New application at the top of the window.
4. In the search box, enter Pega. Select Pega in the search results.
Configure Azure AD single sign-on
To configure and test Azure AD single sign-on with Pega Systems, you need to complete these steps.
1. Enter the name for the application and click the add button. It'll take some time to set up due to the free trial version. It'll open automatically once the setup is done.
2. In the Azure portal, on the Pega application integration page, select Single sign-on.
3. In the Select a single sign-on method dialog box, select SAML to enable single sign-on.
4. The SAML based sign-on of the Application screen will appear. We have to add Identifier, Reply ID and other required details to configure the Single Sign-on.
Before we edit the SAML Configurations, the local host has to be exposed to Public. If you use cloud exposed Pega application this process is not required.
Expose Local Host to Public
We can use ngrok to expose our localhost to public. This exposure is due to security certificate.
1. Go to www.ngrok.com; Signup and create a new account.
2. Download and install ngrok locally.
3. Open ngrok.exe and set up your tunnel by including the token provided in the website of ngrok.
4. Use your port number in the ngrok terminal to start your server.
5. Copy and paste the token in your browser to launch your Pega app locally.
Note: Use the link with https:// to launch a secured browser. And this link is valid only up to 8 hours since we are using the free trial version of ngrok.
Configuring Authentication Service
1. Login to the Pega Application. Click Records >> SysAdmin >> Authentication Service. Create a new Authentication Service.
2. Select SAML in the type. Provide a name for the Authentication Service. Click Create and Open.
3. Provide an Authentication service alias name which will provide a login URL automatically.
4. Scroll down to find Identity Provider (IdP) Information. Copy the Entity Identification (Issuer) URL which is auto-generated. This URL is to be provided in the Azure identifier portal to generate our metadata file.
Basic SAML configuration in Microsoft Azure
1. Click the edit icon in the Setup Single Sign-on with SAML screen in Microsoft Azure in Basic SAML Configuration.
2. Paste the Entity Identification (Issuer) URL copied from Pega in the Identifier field.
3. Type in the Reply URL as shown below and Click Save.
4. Click Save to add the URLs.
5. Click the edit button on the User Attributes and Claims.
6. Select Add new claim to open the Manage user claims dialog box. Add a claim as shown below with name "mail".
7. Click Save to save the claim.
8. Now add a guest user for testing. Go to Azure Active Directory and under manage section click user and create a new guest user to access the application.
9. To create a new user, Click new user.
10. Here we are inviting a user, you can also create a new user if necessary.
11. An invite will be sent to this user. Once the user accepts/approves this invite, they will be able to access the application with this id.
12. Now go back to SAML based Signin screen. Download the Metadata file from SAML Signing Certificate. This File is to be added in our Pega application to fetch URLs.
13. Add ownership to access the application by clicking on "owners" under "manage" section.
14. Now Click on Test in SAML based SIgn-on as a current user or someone else it will redirect to Pega local application as a dev user.
Back to configuring Authentication Service in Pega
1. In the Authentication Service rule, import the downloaded metadata file.
2. After submission, you can see that all the details in Identity Provider (IdP) information is filled automatically.
3. The Service Provider (SP) settings will also be auto-filled.
4. Open the Mapping tab in the Authentication Service rule and add the user claims which were created in Azure and map it to a Pega property. Here we have added "mail" and mapped to .pyUserIdentifier.
5. Include the mapped attribute in the SAML 2.0 tab under Operator Authentication and provide a model operator.
6. Save the Authentication Service rule.
7. To test if this works, Copy the Login URL and paste it in an Incognito window.
8. When you launch this URL a Microsoft Outlook login screen will appear. Provide your Microsoft Outlook login Credentials. This will take you to your PRPC as the modal operator.
9. Your Microsoft ID will also be created as an Operator in your application.
10. You can also customize your login screen by adding a button for logging in using Outlook if necessary.