This article describes how to configure authentication in Pega Platform to use Security Assertion Markup Language (SAML) standard, with miniOrange acting as Identity Provider.
Step One: Create Authentication Service in Pega
Login to Dev Studio of your Pega Platform and click Configure > Org & Security > Authentication > Create Authentication Service. Choose “SAML 2.0” as the authentication type, fill in the name and description, and click “Create and open”.
On the next screen, specify the Authentication Service alias, then scroll down to the Service Provider section of the page and note the following information, which you will need in the next step:
Entity ID from the "Entity Identification" field
ACS URL from the "Assertion Consumer Service (ACS) location" field
Step Two: Create application in miniOrange
Login to the miniOrange console, go to the Dashboard and click the "Try miniOrange as IDP" tile.
On the next screen, choose the SAML tab, and then find application type named "Custom App". You may use the search field to narrow the list of visible application types. Click "Custom App" to create a new application.
Now you need to fill-in the application configuration.
For the Custom Application Name you can use any value, the example below uses "PegaDev"
In the "SP Entity ID or Issuer" field, enter the Entity ID of Pega Authentication Service, which you noted in the previous step. Similarly in the "ACS URL" field enter the ACS URL from the previous step.
In the "Name ID "field you need to specify what that will be used for the value of the NameID element of the SAML Assertion. This value is used to map miniOrange users to Pega operators. In our example we configured it to email address, which means that when a miniOrange user logs in, it will be matched to Pega operator with ID equal to this user's email.
Finally you need to define an authentication policy that will be used by this application.
When you are done, save the application.
Now find your newly created app on the list of your applications, and click the "metadata" link.
This opens a screen with all the information required to use your application-specific Identity Provider. Click "Download Metadata" to save this information in form of an XML file.
Step Three: Configure Authentication Service in Pega
Go back to the Authentication Service configuration in Pega Dev Studio and use the "Import IdP metadata" option to import the metadata file downloaded in the previous step. This will fill-in the Identity Provider section of the service configuration.
In the Service Provider section either configure the keystore for request signing or check the "Disable request signing" checkbox.
Now you can save the Authentication Service.
Step Four: Verify the end-user experience on a desktop
Make sure you have a user in miniOrange, which can be mapped to an operator in Pega by way of email, as described in step two. The operator must have "Use external authentication" checkbox ticked.
Open a new incognito window of a desktop browser and point it to the Login URL of your Authentication Service. The browser should be redirected to the miniOrange login screen. Login in as the aforementioned miniOrange user and verify you are redirected to the Pega application, logged in as the mapped operator.
Step Five: Verify the end-user experience on a mobile
In your Pega Dev Studio, go to Channels and Interfaces and create a new mobile channel. In the Security section of the "Configuration" tab, find the "Select authentication source" dropdown and set it to your Authentication Service.
Build the mobile app and install it on a device. When you run the app for the first time, it will show the screen with "Log in" button. Tapping "Log in" should open an external web browser and load the miniOrange login page. After successful authentication, the end-user will be brought back to your mobile app, which will proceed to prepare your Pega application. When the Pega application starts, you should be logged in as the mapped operator.