Setting up Single Sign-On - Kerberos

Kerberos is one of the authentication protocols supported by the Automation Engine for enabling Single Sign-On (SSO). As a system administrator, you configure Kerberos to integrate your Automic Automation system with your organization’s Key Distribution Center (KDC), such as Microsoft Active Directory.

The Automic Web Interface and the Java Work Processes (JWPs) both require direct access to the KDC to perform authentication. Access only to the Communication Processes (CPs) is not sufficient.

When enabling Kerberos authentication, ensure that a dedicated service user is created in Active Directory for each host that runs the AWI and for each host where a JWP is installed. This allows secure ticket validation for all participating components.

Note: Single Sign-On with Kerberos is not supported in the Automic Automation Kubernetes Edition.

Important! A time difference of five to ten minutes between the AWI and the client system is acceptable. If the time difference exceeds this limit, users may encounter the error message Clock skew too great when attempting to log in.

This page includes the following:

Configuring Kerberos in the Automation Engine and the Automic Web Interface

  1. Create the krb5.conf file on the following directory: <java-home>/conf/security/krb5.conf.

    For more information about configuring the Kerberos file, see https://docs.oracle.com/en/java/javase/11/security/kerberos-requirements.html.

    Example

    [libdefaults]

    default_realm = DOMAIN.SAMPLE

    default_tkt_enctypes = des256-cts-hmac-sha1-96

    default_tgs_enctypes = des256-cts-hmac-sha1-96

    permitted_enctypes = des256-cts-hmac-sha1-96

    [domain_realm]
    .domain.sample = DOMAIN.SAMPLE

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

  2. Restart your application server.

  3. 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), 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.

Enabling and Enforcing SSO for Kerberos

After Kerberos has been configured in your Automic Automation environment, you can enable or enforce Single Sign-On (SSO) in your AWI instance.

Enabling Single Sign-On

To enable SSO for Kerberos in a manually installed system, set the following property in the configuration.properties file located in the AWI config directory:

sso.kerberos.enabled=true

Save your changes and restart the AWI.

Note: Kerberos authentication is not supported in AAKE.

Enforcing Single Sign-On

Administrators can require all users to log in exclusively through Kerberos by enabling SSO enforcement. To do so, set the following property:

sso.kerberos.enforced=true

When enforcement is active, users cannot log in using standard credentials. Authentication is performed only through the configured Kerberos Key Distribution Center (KDC).

For more information, see configuration.properties - Configuring Your Local Setup.

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: