By configuring single sign-on access to your Pega Marketing application, your users can sign in using their existing company username and password. This option is available for regular operators (that is, marketing analysts, managers, and so on), as well as for operators linked to automatic system processes.

This article describes the process for configuring access for your regular operators.

Understanding single sign-on

With single sign-on, you configure Pega to authenticate with your company’s existing authentication infrastructure. This means that users can use their existing username and password to access the Pega system, even if they have not signed into Pega before.

You configure Access Groups in Pega to grant roles and privileges to types of user.

Depending on your company’s authentication infrastructure, you use model operator records to design the access that each kind of user gets granted when they first sign in. This has the effect of creating a Pega Operator record for the user who has signed in, by copying a template Operator and personalising it based on the information (claims) that the authentication service has provided about that user.

You choose an authentication service that matches the identity provider that your existing IT infrastructure provides. Examples of services are SAML, OpenID, Kerberos, and LDAP.

The approach you take to single sign-on is usually decided between the Lead System Architect, the Lead Business Architect, and your IT team. It is usually then implemented by a Senior System Architect as part of implementing a security-related user story.

Configuring single sign-on

1. Ensure you have the pzCanCreateAuthService privilege which is included in the PegaRULES:SecurityAdministrator role.
2. Create the authentication service that matches the type of service your organisation uses by clicking Configure > Org & Security > Authentication > Create Authentication Service.
3. Work with your IT department to configure the appropriate authentication service for your organisation. There are detailed guidelines for each type of authentication service in the Pega documentation. See Creating an authentication service.
4. Choose what authentication attribute (claim) you want to use to uniquely identify your users. This is typically the user’s username or email address. Configure your authentication service to use this claim. For example, in the SAML Authentication Service, you would use Name identifier in the subject to use the default SAML unique identifier, or choose Attribute and map your own value such as {http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress}.
5. Choose what authentication attributes (claims) you want to be mapped from your authentication provider to your Pega operator records, and then:
   1. Work with your IT department to configure the claims that are sent to Pega at authentication time.
   2. In Pega, add mappings to your Authentication Service to map from the claims to the Operator record. You map from the page pxRequestor, or any other page that is available on the clipboard. You can also use the expression builder. Each authentication service has its own source page to map from. For example, the SAML service exposes D_SAMLAssertionDataPage. You can map to the Operator record which is in the page OperatorID. You can also map values to the two data pages D_pyOperatorAttributes and D_pyOperatorDeviceInformation which are used to cache information about the operator and the operator’s device respectively. More details on mappings are available in the individual authentication service documents listed at Creating an authentication service.
6. Configure service-specific elements. Each authentication service has a set of additional configurations that are unique to the type of authentication provider. Use the documentation in the link above to consider if you need to do any of this configuration.
7. If your authentication service supports model operator provisioning (SAML and IODC authentication services do), then create model operator records for each type of operator.
   1. If provisioning model operators by a custom group, create a data transform and data page to populate the operator ID of the model operator using the instructions provided in Provisioning an operator by using a data transform. 
   2. If provisioning model operators by organisation hierarchy, add the hierarchy details.
   3. If provisioning by a custom data transform, add the name of a data transform in the Data-Admin-Operator-ID class.

Outcome

Once the authentication services are configured, all of the users who should be able to access Pega will be able to do so using their existing usernames and passwords, and they will have access to the parts of the application that they should, and will not have access to those parts that they should not.

Frequently asked questions about your single sign-on configuration

What do I do if I can’t get Pega to pick up the Name identifier in the subject?

In Pega 8.1, we have seen that the SAM Account Name in the NameID element within the Subject element (<Subject><NameID>C428286</NameID>) may not be recognised. In this case, ask your IT department to send the value as an additional "normal" SAML claim too, for example samaccountname, and instead of using name identifier in the subject, use an attribute mapping by selecting Attribute or Datapage reference.

How do I secure my Model Operators so that they cannot be used to sign in?

You cannot use the Disable Operator option on a model operator because that value itself is copied to the new operator record, and then the user cannot sign in. Instead, as a best practice, set the Access Group of the model operators to an access group that has no roles and no access. This will prevent anyone from using the model operator record itself to authenticate with the system.

Ensure that the mappings within your authentication service are set up in such a way as to set the Access Group (.pyAccessGroup) appropriately during sign in along with the other claims mappings such as the user’s forename, surname, and email address.

How do I stop a user signing in if they are removed from a group but not deactivated?

Once a user’s operator ID record has been created during the user’s initial sign in, it exists and can be used for authentication. Sometimes, the user’s underlying account (e.g. Active Directory) may be updated by the organisation to place that user into a different group or team which means that the user should no longer have access to Pega. You must ensure that this is handled within your claims mappings. If when determining the correct Access Group that the user should be in (see How do I secure my Model Operators so that they cannot be used to sign in? above), the answer is that they should be in no access group, then be sure to set the Access Group (.pyAccessGroup) back to the default one which has no access.

How do I handle changes between environments, such as different service URLs for Development and Production?

If there are elements of the configuration that change between environments, then use Dynamic System Settings (DSS) to hold the values that change, and reference the DSS in your mappings and/or data transforms.

Further reading

• Security rules and data