Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Dynamically adding roles during user authentication

Updated on June 30, 2021

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.

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.

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.

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.

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.

  1. 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.
  2. 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 the example, PegaRULES:SysAdm4 is the base role. In typical applications, this would be an application-specific role.
  3. Create a base access group, which contains the following:
    • application, work pools, and settings needed to execute the application
    • the base role that you created in step 2.
    • (optional) any roles that are static (shared by all operators who belong to this access group)
  4. Add the base access group to all the operator ID records for your application, including any template operator IDs that support single sign-on.
    In the example, the operator is DynamicRolesSysAdmin.
  5. 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).
  6. Create a Value List text property (named ListOfRoles in the example) in the Code-Security class.
    This property holds the role names that can be added during login.
  7. Modify the ApplicationProfileSetup activity as follows:
    1. 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.
    2. Create the RolePage page, of class Code-Security.
    3. Enter the roles that you want to add to the ListOfRoles property.
      In the example, PegaRULES:SysArch4 is the property value. In most projects, your application queries 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 converts the external name into a Pega Platform role.
    4. With RolePage as the step page, create the following Java step:
      boolean myResult=
      tools.getAuthorizationHandle().setRoles(tools, PRAuthorization.UPDATE_APPEND, myStepPage.getProperty(".ListOfRoles")); 
    5. Remove the RolePage page.
  8. 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.
What to do next:

Test the activity: Log in as DynamicRolesSysAdmin, open the clipboard, and verify that the additional role is added to the pxUserRoleslist.

Use access roles and privileges to limit access to rules and data

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us