How to dynamically add roles during user authentication
An access group defines a static relationship between an operator and a set of roles. During the standard login and authentication process, users acquire their access roles as defined in the Roles list on the Access Group rule form's Access tab. The system adds the value for each role to the pxUserRoles value list within the pxThread.pxSecuritySnapshot page, as seen in the clipboard display:
Some organizations maintain user roles in a system of record that is external to Pega Platform™. In such cases, the best approach is to reference that system of record during login and dynamically add the roles. This approach for associating roles with users eliminates the need to separately maintain access groups and 'operator ID to access group' mappings.
This articles describes how to configure a single access group and activity so that the correct role combination is dynamically added to the operator's clipboard page when they log in.
The following example dynamically adds the PegaRULES:SysArch4 role to an operator whose access group provides only the PegaRULES:SysAdm4 role.
Note: For the sake of illustration, this example uses standard Pega Platform roles. Typically, these are replaced by project-specific roles.
- Create the roles, privileges, and Rule-Access-Role-Obj instances that are required for authorization within your application. The role names should either identically match the roles stored in the external system of record, or enable a one-for-one mapping to be defined between the external and Pega Platform role names.
- Create a separate role and Rule-Access-Role-Obj instances for a base role that all users will share. At a minimum, this role must be configured to permit activity processing in the Code-Security class. In this example, PegaRULES:SysAdm4 is the base role. In typical applications, this would be an application-specific role.
- Create a base access group, which contains:
- Application, work pools, and settings needed to execute the application.
- The base role that you created in step 2.
- Optionally, any roles that are static (shared by all operators who belong to this access group).
- Add this access group to all the operator ID records for your application, including any template operator IDs that support single sign-on. In this example, the operator is DynamicRolesSysAdmin.
- The standard activity Code-Security.ApplicationProfileSetup is an extension point -- an empty activity executed during sign-on, intended for you to override with organization-specific features. Copy the standard ApplicationProfileSetup activity in the Code-Security class into an application ruleset at a level in the ruleset hierarchy that reflects how roles are managed (for instance, enterprise-wide, or only one application).
- Create a
Value Listtext property (named ListOfRoles here) in class Code-Security. This property holds the role names that can be added during login.
- Modify the ApplicationProfileSetup activity as follows:
- (Optional) Enter a precondition on the first line so that the activity exits if an operator logging in should be excluded from dynamic role processing. During initial implementation, test by excluding one or more development operator IDs. Adjust this precondition to meet your requirements.
- Create the RolePage page, of class Code-Security.
- Enter the roles that you want to add to the ListOfRoles property. In this example, 'PegaRULES:SysArch4" is the property value. In most projects, your application will query the external system of record to retrieve the roles. If they are not identical to the Pega Platform role names, create a map value rule that will convert the external name into a Pega Platform role.
- With RolePage as the step page, create the following Java step:
tools.getAuthorizationHandle().setRoles(tools, PRAuthorization.UPDATE_APPEND, myStepPage.getProperty(".ListOfRoles"));
- Remove the RolePage page.
Here is how the activity will look when complete:
- Save the rule.
Note: The activity appends the new roles to the existing access group's list of roles. Each operator gets these roles and any roles defined on the external system of record. The roles listed in the shared access group are always granted and cannot be overridden by adding other roles. Therefore, the roles from the external source of record can only maintain or increase access.
Test the activity
Log in as DynamicRolesSysAdmin, open the clipboard, and verify that the additional role is added to the pxUserRoleslist.
If you are using a custom authentication activity to retrieve user authentication information from LDAP, consider retrieving all of the user's information in a single LDAP request. Your authentication activity can create the RolePage, and populate the ListOfRoles property, which can then be used by the ApplicationProfileSetup activity.