By default, Pega Robot Runtime users authenticate with Pega Robot Manager by using single sign-on authentication; users with all other roles authenticate by using basic authentication. Pega Robot Manager supports basic authentication and single sign-on (SSO) by using either OAuth 2.0 with SAML bearer assertion or Kerberos. You can customize authentication by configuring dynamic system settings in Pega Platform.

When you create user accounts in Pega Robot Manager, the authentication method that is assigned to each user is determined by their specified role and the dynamic system setting that is associated with the specified role.

Configuring OAuth 2.0 with SAML bearer assertion for single sign-on (optional)

Perform the following steps to configure Pega Robot Manager to authenticate client requests from Pega Robot Runtime and Pega Robot Studio with OAuth 2.0 with SAML bearer assertion for 2.0 single sign-on.

1. Export the public certificate from Pega Robotic Automation Security Token Service. For more information, see the Pega Robotic Automation Security Token Service User Guide.
2. Create a keystore record.
   1. Click Create > Security > Keystore.
   2. On the Main tab, click Upload file, and upload the .pfx certificate that you obtained from Pega Robotic Automation Security Token Service.
   3. In the Keystore type field, enter PKCS12.
   4. Click Save.
3. Create an Identity Mapping record.
   1. Click Create > Security > Identity Mapping.
   2. Enter a description and name, and then click Create and Open.
   3. From the Keyspace Location field, press the Down Arrow key and select Upload file.
   4. Click Upload file and then select the .pfx certificate that you obtained from Pega Robotic Automation Security Token Service.
   5. In the Keystore type field, enter PKCS12 as the certificate type.
   6. Confirm your settings by clicking Save.
   7. In the Operator identification field, select Attribute or Datapage reference.
   8. In the Attribute Name field, enter UPN.
   9. Confirm your settings by clicking Save.
4. Create an OAUth 2.0 Client registration record.
   1. Click Security > OAuth 2.0 Client Registration.
   2. Enter a description and client name, and then click Create and Open.
   3. On the Client information tab, clear the Client credentials check box.
   4. Click the SAML bearer check box.
   5. In the Identity mapping field, press the Down Arrow key and select the Identity Mapping record that you created in step 3.
   6. Click Save.
   7. Download the Client ID and Client secret credentials and import them into Pega Robotic Automation Security Token Service.
      1. In the Client Credentials section, click View & download.
      2. In the View & download dialog box, click Download credentials, and then save the file to the appropriate location.
      3. Import the file to Pega Robotic Automation Security Token Service. For more information, see the Pega Robotic Automation Security Token Service User Guide.

Configuring Kerberos authentication for single sign-on (optional)

By default, robots log in to Pega Platform by using basic authentication. You can configure Pega Robot Manager to use Kerberos authentication so that robots log in to Pega Platform by using Kerberos authentication. For more information, see Configuring Pega Robot Manager to use Kerberos authentication for robots.

You can configure Pega Platform to support single sign-on using Kerberos using third-party SPNEGO libraries, or you can use your own Kerberos validation method to authenticate traffic to Pega Robot Manager.

For more information, see Specifying the Kerberos authentication method that Pega Platform uses.

Configuring Pega Robot Manager to use Kerberos authentication for robots

Robot registration is still performed in the same way when robots use Kerberos authentication, and you still perform the same steps. However, after you configure the work queues and work groups into which robots register, you must configure Pega Robot Manager to use Kerberos authentication for robots by performing the following procedure:

1. Configuring service packages to use Kerberos.
2. Configure the work group into which a robot registers, either on the robot or by using a decision table. For more information, see Common Configuration Settings or Assigning to a work group by using a decision table.
3. Setting the order of work group registration.

Configuring service packages to use Kerberos

Configure the API and RoboticsSSO service package to authenticate incoming robot requests to use Kerberos authentication.

1. Configure the API service package.
   1. In the navigation panel of Dev Studio, click Records.
   2. Expand the Integration-Resources category, and then click Service Package.
   3. Click the api service package.
   4. On the Context tab, from the Authentication type drop-down list, select Custom.
   5. In the Authentication service field, enter pyKerberosAuthenticationServiceForRobotManager.
   6. Click Save.
2. Configure the RoboticsSSO service package.
   1. In the navigation panel of Dev Studio, click Records.
   2. Expand the Integration-Resources category, and then click Service Package.
   3. Click the RoboticsSSO service package.
   4. On the Context tab, from the Authentication type drop-down list, select Custom.
   5. In the Authentication service field, enter pyKerberosAuthenticationServiceForRobotManager.
   6. Click Save.

Specifying the Kerberos authentication method that Pega Platform uses

Configure the EnableDefaultKerberosAuthenticationForRobotManger dynamic system setting to specify which Kerberos authentication method you want to use to authenticate traffic to Pega Robot Manager. You can either use the in-built capability that provides support for third-party SPNEGO libraries or use your own method of Kerberos authentication.

1. In the navigation panel of Dev Studio, click Records.
2. Expand the SysAdmin category, and then click Dynamic System Settings.
3. Click the record with the pegarobotics Owning Ruleset and EnableDefaultKerberosAuthenticationForRobotManger Setting Purpose.
4. On the Settings tab, in the Value field, enter one of the following values:
   • true: Pega Robot Manager authenticates the service principal name (SPN) from a Kerberos ticket, using the default authentication using SPNEGO libraries, which you configure. For more information, see Enabling Pega Platform to support single sign-on using Kerberos.
   • false: Pega Robot Manager does not authenticate the Kerberos ticket and reads the SPN to validate the operator ID of the requesting robot to establish a session with it. You can then configure your own method of Kerberos authentication.
5. Click Save.

Enabling Pega Platform to support Kerberos single sign-on

On a running Active Directory (AD) server, you can enable Pega Platform, running on an Apache Tomcat server, to use Kerberos authentication. Enabling single sign-on (SSO) by using Kerberos comprises the following steps:

1. Configuring AD to use Kerberos.
2. Configuring Tomcat to enable client systems to connect to Pega Platform.

Step 1: Configuring Active Directory to use Kerberos

After you create users and systems inside an AD domain, define the Pega Platform server and configure service principal names (SPNs) for users. Kerberos uses SPNs, which uniquely identify service instances, to associate a service with a service logon account.

1. Enter either the ktpass.exe or setspn.exe command to map the Pega Platform server and Pega Platform users to their server and client systems. On the domain controller server, which is the system on which Active Directory Domain Services (AD DS) is running, do one of the following actions:
   • To run the ktpass.exe command, for example, for a KerbServUser server and KerbClientUser user, open the command line and enter the following commands, where DOMAINNAME.COM is your fully qualified domain name, and SERVERHOSTNAME is the name of your Pega Platform system:

     ktpass.exe /out c:\KerbServUser_SPN.keytab /mapuser [email protected] /princ

     HTTP/[email protected] /pass password

     /crypto all /ptype

     KRB5_NT_PRINCIPAL /kvno 0

     TRHOSTNAME SPN and the C:\KerbServUser_SPN.keytab.keytab file for this SPN. The keytab file contains the SPN credentials.

     You can use the generated .keytab file to provide login credentials to Tomcat by modifying the web.xml and login.conf files. For more information, see Step 4 in Configuring Tomcat to enable client systems to connect to Pega Platform.

   • To use the setspn.exe command to configure SPNs without using a .keytab file, open the command line and enter the following commands, ensuring that all computers and users are in the same domain:

     Setspn.exe -A HTTP/SERVERHOSTNAME KerbServUser

     Setspn.exe -A HTTP/[email protected] KerbServUser

     Setspn.exe -A HTTP/SERVERHOSTNAME.DOMAINNAME.COM KerbServUser

     Setspn.exe -A HTTP/[email protected] KerbServUser

     Do not register an SPN to more than one user name. A user name can have more than one SPN registered, but an SPN can be mapped only to one user.
     To display the SPNs for a user, use the command: setspn –l<user_name>
2. Enable delegation for users by clicking Trust this user for delegation to any service (Kerberos only) in Active Directory.
3. Configure the Kerberos policy to use AES-128 bit encryption on both the domain controller server and on the system running the Apache Tomcat server.
4. Enable AES-128 bit encryption for the user.

Step 2: Configuring Tomcat to enable client systems to connect to Pega Platform

Configure Tomcat with SPNEGO libraries so that client systems can connect to Pega Platform.

1. Create the login.conf and krb5.conf files, and add them to the $catalina_home/bin Tomcat folder.
2. Download the spnego-r7.jar file from the SourceForge website and copy it to the prweb/WEB-INF/lib Tomcat folder.
3. Modify the web.xml file to intercept REST endpoints to enable negotiation and authentication for RPA calls that are requested by Pega Robot Runtime and Pega Robot Studio from the Pega Platform server. Use <filter-mapping> tags only for the endpoints (requested URLs) that are available for the api and SSO service packages.

   By default, SPNEGO uses NTLM on basic authentication modes if there is a failure with using Kerberos. Therefore, you can use <filter-mapping> tags as a generic method to intercept all the incoming traffic to the Pega Platform server. NTLM and basic authentication modes are applied to each request to the Pega Platform server.

4. Add the following code to the web.xml file to intercept the endpoints that are available for the api and roboticsSSO service packages, providing the appropriate values for parameters such as the spnego-client:

   <filter>
   	<filter-name>SpnegoHttpFilter</filter-name>
   	<filter-class>
   		net.sourceforge.spnego.SpnegoHttpFilter
   	</filter-class>
   	<init-param>
   		<param-name>spnego.allow.basic</param-name>
   		<param-value>true</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.allow.localhost</param-name>
   		<param-value>true</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.allow.unsecure.basic</param-name>
   		<param-value>true</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.login.client.module</param-name>
   		<param-value> spnego-client</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.krb5.conf</param-name>
   		<param-value>krb5.conf</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.login.conf</param-name>
   		<param-value>login.conf</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.allow.delegation</param-name>
   		<param-value>true</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.preauth.username</param-name>
   		<param-value>username</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.preauth.password</param-name>
   		<param-value>password_for_pre_auth_user</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.login.server.module</param-name>
   		<param-value>spnego-server</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.prompt.ntlm</param-name>
   		<param-value>true</param-value>
   	</init-param>
   	<init-param>
   		<param-name>spnego.logger.level</param-name>
   		<param-value>1</param-value>
   	</init-param>
   </filter>
   <filter-mapping>
   	<filter-name>SpnegoHttpFilter</filter-name>
   	<url-pattern>/PRRestService/roboticsSSO/*</url-pattern>
   </filter-mapping>
   <filter-mapping>
   	<filter-name>SpnegoHttpFilter</filter-name>
   	<url-pattern>/api/*</url-pattern>
   </filter-mapping>
   <filter-mapping>
   	<filter-name>SpnegoHttpFilter</filter-name>
   	<url-pattern>*.jsp</url-pattern>
   </filter-mapping>
   <login-config>
   	<auth-method>SPNEGO</auth-method>
   </login-config>
   

5. Configure preauthorization user credentials by doing one of the following actions:
   • Modify the web.xml file and provide the values for the SPN user name and password in the following parameters:

     <init-param>
     <param-name>spnego.preauth.username</param-name>
     <param-value>username_of_pre_auth_user</param-value>
     </init-param>
     <init-param>
     <param-name>spnego.preauth.password</param-name>
     <param-value>password_for_pre_auth_user</param-value>
     </init-param>
     

   • Modify the spnego-server module in the login.conf file to provide information about the .keytab file. For more information, see step 6-c.
6. Configure the login.conf file by performing the following actions:
   1. Add the following text to the login.conf file:

      spnego-client {com.sun.security.auth.module.Krb5LoginModule required;
      };spnego-server {com.sun.security.auth.module.Krb5LoginModule
      Required
      useKeyTab=false
      storeKey=true
      debug=true
      isInitiator=false;
      };
      

   2. Modify the values for the spnego - client and spnego -server module names to match the values that you provided for the following entries in the web.xml file in step 3:

      <init-param>
      <param-name>spnego.login.client.module</param-name>
      <param-value>spnego-client</param-value>
      </init-param>
      <init-param>
      <param-name>spnego.login.client.module</param-name>
      <param-value>spnego-client</param-value>
      <init-param>
      

   3. Configure preauthorization user credentials by setting the following values:
      • ​useKeyTab=true.
      • HTTP/SERVERHOSTNAME is the SPN
      • C:\KerbServ_SPN.keytab is the name and location of the .keytab file.
   4. ​Configure the krb5.conf file to identify the domain realm name and the IP address of the AD DS system on which the Kerberos Key Distribution Center (KDC) network service runs. Modify the following text, where DOMAINNAME is the domain name of the Kerberos realm, which is the domain over which Kerberos can authenticate users, and KDCMACHINEIP is the IP address of the AD DS.

      [libdefaults]
      default_realm = DOMAINNAME.COM
      default_tkt_enctypes = des3 -cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
      aes128-cts-hmac-sha1-96 aes128-cts
      default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
      aes128-cts-hmac-sha1-96 aes128-cts
      permitted_enctypes= des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
      aes128-cts-hmac-sha1-96 aes128-cts
      [realms]
      DOMAINNAME.COM = {kdc = KDCMACHINEIP:88
      default_domain = DOMAINNAME.COM}
      [domain_realm]
      .domainName = DOMAINNAME.COM
      domainName = DOMAINNAME.COM
      

   After setup is complete, you can verify that Pega Platform is configured for SSO using Kerberos by verifying that when a client system makes a request to Pega Platform, the Authorization header starts with Negotiate, followed by a Kerberos ticket.