Setting up Single Sign-On - Kerberos

The Kerberos Key Distribution Center (KDC) is one of the protocols supported by the Automation Engine for single sign-on. As a system administrator, you set up Kerberos to use it with your system.

Important!

  • Time differences of five to ten minutes between the Automic Web Interface and your client are permissible. If the time difference is significant, end users might get the Clock skew too great error message on login.

  • The Automic Web Interface and the Java Work Process (JWP) require access to the KDC (such as the Active Directory in Windows). It is not enough to have access to the communication processes (CP).

  • Multiple service users must be created in the Active Directory for each host running the Automic Web Interface and for each host where a JWP runs.

This page includes the following:

Configuring Kerberos in the Automation Engine and the Automic Web Interface

  1. Install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy on hosts in which the AWI and the Automation Engine (JWP) run.

    If necessary, add JCE to your application server. You can download it from Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.

    The Readme file contains the installation instructions. If there are multiple Java installations on the same host, it is recommended to set up a policy file for all installations.

  2. Configure the Kerberos file on the AWI server.

    The krb5.conf file must be created in all other cases. The configuration file is located in the same folder as the JCE: <java-home>/lib/security/krb5.conf.

    For more information about configuring the Kerberos file, see https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html.

    Example

    [libdefaults]

    default_realm = DOMAIN.SAMPLE

    default_tkt_enctypes = rc4-hmac

    default_tgs_enctypes = rc4-hmac

    permitted_enctypes = rc4-hmac

    [domain_realm]
    .domain.sample = DOMAIN.SAMPLE

    [realms]
    DOMAIN.SAMPLE = {
    kdc = servername.domain.sample
    admin_server = servername.domain.sample
    }

  3. Restart your application server.

  4. Enable KDC in the UC_SYSTEM_SETTINGS. For more information, see KDC.

After Kerberos has been successfully configured, you can enable single sign-on in your AWI instance. To do so, set the sso.kdc.enabled property in the configuration.properties file to true. For more information, see configuration.properties - Configuring Your Local Setup.

Configuring Kerberos in the JWP

As a system administrator, you generate the keytab file for each AWI host.

  1. Create a service user in the Microsoft Active Directory for each host where a JWP runs. This user is used for authentication between the JWP and the Microsoft Active Directory. The user password should not expire. Activate the account option This account supports Kerberos.

    For more information, see Windows Configurations for Kerberos Supported Encryption Type.

  2. Create Service Principal Name (SPN) on the Kerberos Administration Server.

    To implement single sign-on for web applications (such as AWI or CDA), you need a keytab file with HTTP as Service Principal Name.

    Example

    HTTP/winhost01.domain.sample@DOMAIN.SAMPLE

    In this example, winhost01 is the host on which the AWI (application server) is installed.

    Notes:

    • You want to create SPNs for each AWI host (one SPN with the host name and one with the fully qualified domain name). Pay attention to uppercase and lowercase letters when creating SPNs. Otherwise, the name may not be found in the Kerberos database.

    • The realm is optional. If it is not specified, the default value from the configuration file krb5.conf is used. In Windows, the Kerberos realm name is the domain name (DNS suffix) in uppercase letters (such as DOMAIN.SAMPLE).

    For more information, see Detailed description of Kerberos principals.

    The SPNs must be assigned to the previously created KDC service user.

    If the Automation Engine runs on more than one host, then the previous steps must be performed for each of the AE hosts. Each AE host must have its own associated service user, and the SPNs must be created for each of these service users. In Microsoft's Active Directory, you can use the command setspn to create SPNs.

    Example

    setspn -s AEServer01/winhost01.sample.host@DOMAIN.SAMPLE ServiceAccount01
    setspn -s AEServer01/winhost01@DOMAIN.SAMPLE ServiceAccount01

    setspn -s AEServer02/winhost02.sample.host@DOMAIN.SAMPLE ServiceAccount02

    setspn -s AEServer02/winhost02@DOMAIN.SAMPLE ServiceAccount02

  3. Generate keytab file on the AWI server.

    In Microsoft Active Directory, you can use the command ktpass to generate a keytab file. You must specify the SPN, KDC user, KDC user's password, path/file name of the keytab file and the parameter /mapuser.

    ktpass /princ HTTP/awihost.domain.sample@DOMAIN.SAMPLE /mapuser ServiceAccount01@DOMAIN.SAMPLE /pass ServiceAccountPass /mapop set /crypto all /out c:\temp\AE.keytab -ptype KRB5_NT_PRINCIPAL

    The keytab file C:\temp\AE.keytab is created.

    You can also create the keytab file on the Kerberos Administration Server.

    For more information about the ktpass command syntax, see http://technet.microsoft.com/en-us/library/cc753771.aspx.

    Important! If the AWI is deployed on different hosts, the steps for generating the keytab file (steps 2 and 3) must be performed for each host name which results in extra keytab files. However, given the JWP requires exactly one file, these entries must be merged into one file.

    On UNIX you can use the application ktutil to merge the entries into one file with the following commands:

    ktutil

    rkt keytab1.keytab

    rkt keytab2.keytab

    wkt merged.keytab

    The resulting file containing the entries of keytab1 and keytab2 is named merged.keytab.

    Because the Java for Windows has no merge parameter, the simplest solution is to merge the two files using ktutil on a UNIX system and then transfer the merged file to your Windows installation.

  4. Specify the keytab file by entering the path and file name of the generated keytab file in the UC_KDC_SETTINGS variable. For more information, see UC_KDC_SETTINGS - Single Sign-On.

    Notes:

    • Restart the Java Work Process (JWP) after changing a setting in a system variable.

    • If there are multiple JWPs on different hosts, the keytab file must be located in the same directory on all hosts. If the file is missing on one or more hosts, login might not always work.

Losing the Kerberos Connection

If you lose the Kerberos connection, the login dialog is displayed regardless of your previous choices and it shows a warning message.

This can happen if you log in from a computer or server that is not in the Windows domain where Kerberos is installed, or if there is a problem in the Kerberos configuration. In this case, Windows tries to authenticate with Windows NT LAN manager (NTLM) which cannot process the Kerberos authentication information.

In the meantime, the login defaults to the standard login. For more information, see Standard Login.

Users for Authentication

After Kerberos has been successfully configured, the corresponding users must be created in the clients of the Automation Engine system. The user names must correspond to the OS users names who should be granted access with single sign-on.

The department is irrelevant as long as the user name is unique for each client. If there are two or more users with the same name but a different department, each of these departments must be assigned to a domain in the UC_KDC_SETTINGS variable. For more information, see UC_KDC_SETTINGS - Single Sign-On.

Single sign-on login fails if no User object (USER) exists in the selected client with the same name as the OS user, such as the one used for launching the AWI.

Example

The AWI is launched in Windows under the user TEST/LOCAL. AE system TEST, client: 100.

If there is no User object with the name TEST/* (department irrelevant) in client 100, single sign-on login is not possible. If there are several users in client 100 with the name TEST/* (such as TEST/DEV and TEST/LOCA"), the departments must be assigned to the domains of the OS users. If departments are not assigned, login also fails.

Troubleshooting

  1. Get all SPNs of a service user.

    To check the SPN registration of a user use the following parameter:

    setspn -L automicawi

    The result should contain the HTTP SPN.

    Example

    Registered ServicePrincipalNames for CN=automic awi,CN=Users,DC=domain,DC=sample:

    HTTP/winhost01.domain.sample@DOMAIN.SAMPLE

  2. Start the JWP with Kerberos debugging.

    Disable it in the ServiceManager so that only one JWP is running for the debugging procedure. Start the JWP from a console window because this is where the output is written to:

    java -Xmx2G -Dsun.security.krb5.debug=true -jar ucsrvjp.jar

    This prints Kerberos debug output to stdout (default output).

  3. Test if you are able to get a TGT from Kerberos.

    java "-Dsun.security.krb5.debug=true" "-Djava.security.krb5.conf=C:\JDK\jdk1.8.0_101\jre\lib\security\krb5.conf" sun.security.krb5.internal.tools.Kinit -k -t C:\AWA\Automation.Platform\AutomationEngine\bin\AE.keytab HTTP/winhost01.domain.sample@DOMAIN.SAMPLE

See also: