Customizing Basic authentication in Pega

December 10, 2024 Code Vault Curators

In the last post, we saw how the default basic authentication works in Pega. In this post, we will see how we can customize and have our own basic authentication.

This blog article is implemented using 8.2 version

Now the first question is why do we need to customize the basic authentication?

1. When the user credentials are not saved in Pega DB

We saw in the previous post that the default basic authentication always checks the credentials in pega database. What if the credentials are stored in external system. I am not talking about LDAP directories, just imagine the credentials are in an external system database. You can customize the basic authentication service to validate the credentials against an external data store.

2. When you need to perform user provisioning and attributes mapping

From the first point we saw that the credentials can be in different system and not in pega database. So, we may need to create new operator IDs and map the right attributes.

3. To perform the pre and post authentication activities

These are the main three reasons why we usually customize the default basic authentication.

First let’s start with checking out the existing basic authentication service.

Records -> SysAdmin -> Authentication Services

Click and open the AuthService type = Basic Credentials

You see the interesting part is Login URL.

http://localhost:8080/prweb/PRAuth/pega

Launch the URL and you see the login page.

Now instead of the default internal basic authentication, the basic authentication service rule what we saw before got executed. I will get back to this later.

let’s explore all the configuration points in the authentication service rule.

Create a new authentication service rule

Records –> SysAdmin -> Authentication Service

Select Authentication type as Basic Credentials

Click create.

You will see 3 main tabs

Basic credentials
Mapping
Security policies

Basic Credentials tab

Enable authentication service – The name speaks. Only on selecting this checkbox, the authentication service will be enabled.

Authentication service alias – You need to specify a unique name for your authentication service.

As highlighted in the above picture, the alias name you specify forms the login URL resource path, so make sure you keep it clean and simple 😊

Login URL – read only; It automatically appends with prweb/PRAuth/{alias name}

Launch the login URL – http://localhost:8080/prweb/PRAuth/facebook

Verify credentials in external identity store

Next interesting thing is Verify credentials using external identity store.

I am getting back to the introduction scenario, where the credentials are stored in an external database. Select the checkbox.

A new field is visible now. Data page for credential verification. So Pega asks us to verify the credentials using a data page.

Now you may get a question, how this authentication service will know, if the credential verification is a success or a failure?

So Pega’s restriction comes into play 😊. Cool usually Pega don’t restrict his developers 😉

Following are the restrictions

1. The data page should be read only page in requestor scope.

2. The object type and the applies to class should be in Data-Admin-Operator-ID.

3. The data page should be saved in unauthenticated ruleset with two parameters – username and password.

4. The data page source can be data transform / activity in Data-Admin-Operator-ID, saved in unauthenticated ruleset.

5. Specify two request parameters, username and password. When the credentials are successfully validated, set the property .pyApproveStatus to true.

Why such restrictions?

Pega internal engine passes the credentials in username and password parameters and expects the verification results in pyApproveStatus property. It is all hidden inside!!

Let’s build the data page.

Step 1: Create a new data page as per the below configuration.

Step 2: Create either data transform or data page. I am going to create a data transform

Don’t forget to mention the parameters.

For now, I hardcoded the pyApproveStatus to true. Ideally in really time you integrate with another system and decide whether the credentials are validated successfully. So pyApproveStatus value will be decided based on the external system validation.

Step 3: Save the data transform as the source.

Step 4: Finally save the data page in the authentication service rule.

Look how intelligent Pega is!! Pega knows, you forgot to specify the username and password as parameters in the data page.

Step 5: Specify the username and password as parameters to the datapage and save the rule.

Now you can resave the authentication service rule.

Let’s test this verification part.

Note: Now the credentials will be verified in the external system.

Just launch the designer studio and provide an existing username and some random junk password.

You should be logging in successfully 😊. You know why! Since I hardcoded the verification as success, Pega always lets in the operator login without verifying the password in its internal operator table.

Now try with an operator who is not in pega database but in external system, pega throws error.

So, the next functionality comes in picture. Provisioning operators.

Provisioning operators

The authentication service can create operators on the fly when the credentials are verified successfully in the external system.

How to provide user provisioning?

Whenever you check – verify credentials using external identity store, you get an option to perform user provisioning. This is because, we cannot guarantee that all operators in the external identity store system will be available in the pega operators table.

Select the enable operator provisioning using model operator.

Imagine you are logging in into pega application for the first time. Your credentials reside only in the external identity store and not in Pega database.

When you login for the first time, the authentication service should create a new operator record. For creating a new operator record, you need to know the basic details like, which access group the operator should point to, which organization hierarchy it should come under. So, these details, the operator context, can be set by 3 ways.

a) By name – You can specify any existing model operator. So, your new operator will be like a save as of the existing operator.

b) By organization hierarchy –

Here, we input only Organization, Division and Unit name! Then how we can set the other context like, access groups etc?!

Remember, Unit instance can include a model operator corresponding to that organization Unit.

This will be used as a model operator for user provisioning.

c) Data transform

Here, you can specify a data transform rule created in the Data-Admin-Operator-ID to copy the operator context. For your reference, you can look into the OOTB rule – pyDefaultForNonPegaOperator

For now, I am going to use my operator as the model operator in the first option.

Let’s test the user provisioning now

Step 1: launch the new auth service URL.

Step 2: Try to login with an operator, who is not available in the pega database.

Step 3: You should be seeing, Thor able to login the pega application and a new operator for him is created on the fly.

Step 4: Go to Records -> Organization ->Operator ID and click on it.

You see the new operator ID Thor has the same operator context as Prem 😉

Thor has entered the Pega world!!

Hope you understood how this operator provisioning works in auth service!

Let’s check on other fields in the auth service rule and wrap up the tutorial.

Map operator ID –

You can leave this field as such, because pega uses the logging in user name in the object name – username.

Advanced configuration settings

Use access group timeout – This serves as an extra layer of security, where you can prompt the users to enter the credentials again after a certain period of inactivity. The timeout interval will be the time specified in the access group instance.

Pre-authentication and Post-authentication activity –

Pre-authentication activity should be in UnAuthenticated ruleset and post-authentication activity should be in the operator’s access group application accessible stack.

The activity should be in Code-Security class

The activity should set the value pyAuthenticationPolicyResult to true or false based on your requirement. True for success.

I give you a requirement, where you should allow only the desktop devices access your application. This is the pre-authentication requirement and can be handled in pre-authentication activity.

For you reference, please search and open the activity – pySSOPreAuthenticationActivity

You see the activity finds the property in page pxRequestor.pxIsMobileDevice and verifies if the device is mobile or not.

Let’s test the pre-authentication activity.

For tutorial purpose, temporarily I am going to restrict application access to desktop devices.

Step 1: Save as the activity in the unauthenticated rule in different name.

Step 2: Uncomment the java step and change the if condition as shown below.

What we are trying in the java code is accessing the pxRequestor page and only when the request is from mobile device we set the result to true.

Step 3: Specify the pre authentication activity in the auth service rule and save the rule.

Step 4: Launch the login URL. Boom.

Post authentication

Imagine a scenario, where you should allow only specific group of users to allow accessing the application and deny access to other user groups. This group or role can be determined only after authentication, so it be a post authentication activity.

The activity should be same like the pre authentication we saw before.

Pega already has a nice OOTB rule ‘pySSOPostAuthenticationActivity’. You can explore the same scenario example there 😊