Skip to main content


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

Configuring Apache Tomcat to support Kerberos/SPNEGO authentication for Pega Robot Manager users

Updated on June 18, 2021

This use case demonstrates how to configure Kerberos authentication for Pega Robot Manager users on a Pega Platform implementation that is running on an Apache Tomcat server.

The configuration process consists of configuring service principal names (SPNs) for Robot Manager users and uploading the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) libraries to Tomcat, so that users can connect to Pega Platform.

Configuring Active Directory to support Kerberos authentication

Configure Active Directory to enable single sign-on authentication through Kerberos for Pega Robot Manager users.

  1. On the domain controller server that is running the Active Directory Domain Services (AD DS), map the Pega Platform server and Pega Platform users to their server and client systems:
    ChoicesActions
    Configure SPNs by using a keytab file.
    1. Open the command window.
    2. Enter the following command:
      ktpass.exe /out c:\KerbServUser_SPN.keytab /mapuser [email protected] /princ
      
      HTTP/[email protected] /pass password
      
      /crypto all /ptype
      
      KRB5_NT_PRINCIPAL /kvno 0
      Where:DOMAINNAME.COM is your fully qualified domain name.SERVERHOSTNAME is the name of your Pega Platform system.

      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 Configuring Tomcat to establish user connectivity to Pega Robot Manager.

    Configure SPNs without using a keytab file.
    1. Open the command window.
    2. 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
      Note: 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 to only one user.
    Tip: To display the SPNs for a user, use the setspn –l<user_name> command.
  2. In Active Directory, enable delegation for users by selecting the Trust this user for delegation to any service (Kerberos only) option.
    See the following figure for reference:
    Enabling delegation for users for Kerberos in Active Directory
    Use Active Directory to enable delegation for users when authenticating through Kerberos
  3. Configure the Kerberos policy to use AES-128 bit encryption on the domain controller server and on the system hosting the Apache Tomcat server.
    For more information, see the Active Directory provider documentation.
    Caution: Check with your system administrator whether the system is using the default RC4 encryption. If the system is using the RC4 encryption, enabling the AES-128 Kerberos group policy on the domain controller server can cause the existing infrastructure to become inoperable.
  4. Enable AES-128 bit encryption for the user.
    Tip: For added security, you can use AES-256 encryption. Download the Java Cryptography Extension (JCE) Unlimited Strength security libraries from the Oracle website and place them in the jre/lib/security and jdk/jre/lib/security directories. You must also change the Kerberos group policy to use AES-256 bit encryption.
    For more information, see the Active Directory provider documentation.

Configuring Tomcat to establish user connectivity to Pega Robot Manager

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

Because Pega Robot Manager does not provide SPNEGO libraries, you must download them separately.
  1. In Tomcat, create the login.conf and krb5.conf files, and add them to the /bin folder.
  2. Download the spnego-r7.jar file from the SourceForge website and copy the file to the prweb/WEB-INF/lib Tomcat folder.
  3. Modify the web.xml file to intercept REST endpoints, to enable negotiation and authentication for calls that are requested by Pega Robot Runtime and Pega Robot Studio from the Pega Platform server.
    Note:

    Use <filter-mapping> tags only for the endpoints (requested URLs) that are available for the API and SSO service packages.

    By default, SPNEGO uses NT LAN Manager (NTLM) in 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 incoming traffic to the Pega Platform server. NTLM and basic authentication modes are applied to each request to the Pega Platform server.

    For more information, see the Apache Tomcat documentation.
  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>/api/roboticsSSO/*</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 pre-authorization user credentials by performing 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> 
    • Provide information about the .keytab file by modifying the spnego-server module in the login.conf file.
  6. Configure the login.conf file:
    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 pre-authorization user credentials by setting the following values:
      useKeyTab=trueHTTP/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 by modifying the following text:
      [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 
      Where:DOMAINNAME is the domain name of the Kerberos realm, which is the domain over which Kerberos can authenticate users.KDCMACHINEIP is the IP address of the AD DS.
What to do next: Verify your configuration by confirming that when a client system makes a request to Pega Platform, the Authorization header starts with Negotiate, followed by a Kerberos ticket.

    • Previous topic Selecting the Kerberos method for authenticating Pega Robot Manager users
    • Next topic Updating the robotics configuration files for single sign-on authentication through Kerberos

    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.

    Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

    Close Deprecation Notice
    Contact us