Administration Guide > Installation > New Installation > Setting up Single Sign-On

Setting up Single Sign-On

The following document contains detailed instructions on how to set up Single Sign-on (SSO) for the Automation Engine system. Single Sign-on makes it possible to login without having to enter login details.

Kerberos KDC (Key Distribution Center) is used for Single Sign-on. If Single Sign-on is configured correctly, it is possible to login (UserInterface, Enterprise Control Center) to the Automation Engine system without having to enter login details (user, departmentDepartment name to which the Automation Engine user belongs. and passwordA secret combination of characters for a Automation Engine user.). The operating system user under which the UserInterface has been launched will be used for authentication.

These installation instructions apply to Windows and UNIX.

General Requirements

JWP:
At least one JWP (Java-based work process) must be active.
Time differences
Times on the client computer (UserInterface, Java API) and server computer (JWP) must not differ significantly. A difference of 5-10 minutes is permissible depending on the setting. If the difference is too great, you may see the error message "Clock skew too great" on login.
Access to KDC
UserInterface and JWP require access to the KDC (for example, Active Directory in Windows). It is not sufficient for the UserInterface to have access to just the CP, for example.

Installation steps for the UserInterface and Automation Engine

	1)	Registry key for TGT access

This step is required only if the UserInterface runs in Windows.

This registry key is required so that Kerberos Java implementation can use an existing TGT (Ticket Granting Ticket). The TGT will be generated by logging in to the operating system.

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters]
"allowtgtsessionkey"=dword:00000001

	2)	Installation of Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy

The JCE Unlimited Strength Jurisdiction Policy has to be installed on the machines where:

The UserInterface and/or the ECC runs.
The Automation Engine (JWP) runs.

Download under Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy

For IBM Java, you must use the policy files of IBM. The unlimited jurisdiction policy files are located in directory SDK /demo/jce/policy-files/unrestricted/.
See

https://www.ibm.com/support/knowledgecenter/en/SSYKE2_7.1.0/com.ibm.java.security.component.71.doc/security-component/sdkpolicyfiles.html

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

	3)	Kerberos configurationA set of constituent components that make up a system. This includes information on how the components are connected including the settings applied. file

This step can be omitted if the UserInterface runs in Windows with Java Version 1.7. With Java 1.7, the settings will be identified immediately in Windows.

The krb5.conf file should be created in all other cases. The location of the configuration file is <java-home>/lib/security.

The exact search sequence is described under http://download.java.net/jdk8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html in the section "Locating the krb5.conf Configuration File". The Kerberos documentation describes how to set up this file.

Example:

[libdefaults]
default_realm = DOMAIN.SAMPLE
[domain_realm]
.domain.sample = DOMAIN.SAMPLE

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

	4)	Enable KDC in the AE system-wide settings

In the UC_SYSTEM_SETTINGS file, set KDC to Y to enable Kerberos Distribution Center (KDC) authentication for a whole system.

Installation steps for the JWP

Generate key tab file

The following steps must be performed by the KDC administrator (for each CP host):

	1)	Create a service user in the KDC

Create a new service user in the KDC (for example, in the Active Directory in Windows) which is to be used for authentication. The user password should not expire.

	2)	Create Service Principal Name (SPN)

Service Principal Names (SPN) must then be created with the following description:
<AE System Name>/<CP Host Name>[@<Realm>]
<AE System Name>/<Fully qualified Domain Name of the CP Host>[@<Realm>]

Automic recommends creating SPNs for each CP host (one SPN with the host name and one with the fully qualified domain name).

Make sure you pay attention to upper and lower case letters when creating SPNs. Otherwise, the name may not be found in the Kerberos databaseA database is an organized collection of data including relevant data structures..

The realm is optional. If this is not specified, the default value from the configuration file krb5.conf will be used. In Windows, <Realm> always corresponds to the domain name (DNS suffix) in upper case letters (for example: DOMAIN.SAMPLE)

Also see: Detailed description of Kerberos principals.

Example:
AEServer01/winhost01.domain.sample@DOMAIN.SAMPLE

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

In Microsoft's Active Directory, the command "setspn" can be used to create SPNs. As stated above, creating an entry for the host name and one for the fully qualified domain name is recommended.
Example:

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

	3)	Generate keytab file

A keytab file must be generated in this step.

In Microsoft Active Directory, the command "ktpass" can be used for this. The SPN, KDC user, KDC user's password, and path/file name of the keytab file must be specified.

Example:

ktpass /princ AEServer01/winhost01.domain.sample@DOMAIN.SAMPLE /mapuser ServiceAccount01@DOMAIN.SAMPLE /pass UXTY5rdx+!1245.qw /mapop set /crypto all /out c:\temp\ae.keytab -ptype krb5_nt_principal

The keytab file C:\temp\ae.keytab will then be created.

Details of "ktpass" command syntax: http://technet.microsoft.com/en-us/library/cc753771.aspx

In case you get an error message, when trying to generate the .keytab-file, you should use the following additional switch with the example above:

-ptype KRB5_NT_PRINCIPAL

Reason for this error would be the fact, that you are not mapping the SPN to a principal. KRB5_NT_PRINCIPAL is the general principal type (recommended) as documented by Microsoft.

Multiple CPs on Different Hosts

If the communication processes of the Automation Engine system run on different hosts, then the steps for generating the keytab file (steps 2 and 3) must be performed for each host name.

This will result in additional keytab files. However, the JWP requires exactly one file, which means the entries must be merged into one file.

On UNIX you can use the application 'ktutil' with the following commands:

ktutil

rkt keytab1.keytab

rkt keytab2.keytab

wkt merged.keytab

Thereby a new file named "merged.keytab" is being created, which contains the entries of keytab1 and keytab2.

Since the Oracle 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

Now enter the path and file name of the generated keytab file in the Variable object UC_KDC_SETTINGS, which is located in client 0.

Specify the value "KEYTAB" in the Key column of the Variable object and the key tab file in the column "Value 1".

The JWP must be restarted following a change of 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, then login will not always work.

	5)	SSO configuration for web applications

In order to implement Single Sign-on for web applications (such as Enterprise Control Center or Application Release Automation), a keytab file with HTTP as Service Principal Name is required.

For example:
HTTP/winhost01.domain.sample

In this example, winhost01 is the host on which, for example, the Enterprise Control Center (Tomcat) is installed.

The SPN name must also be entered in the variable UC_KDC_SETTINGS using the "HTTP" key. If several ECC/ARA installations are available for an Automation Engine system, then other names separated by a semi colon can be added.

Example:
HTTP/winhost01.domain.sample;HTTP/winhost02.domain.sample

Users for Authentication

Following successful completion of the configuration, corresponding users must be created in the clients of the Automation Engine system.

The user names must correspond to those of the operating system users, who should be granted access via Single Sign-on.

The department is irrelevant as long as the user nameName of the Automation Engine user. 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 variable UC_KDC_SETTINGS.

Single Sign-on login will fail if no User object exists in the selected client with the same name as the operating system user, such as the one used for launching the UserInterface.

Example:

The UserInterface is launched in Windows under the user "test\local".
AE system TEST, client: 100

If no user object with the name "TEST\*" (department irrelevant) exists in client 100, Single Sign-on login is not possible.

If there are several users in client 100 with the name "TEST\*" (for example, "TEST\DEV" and "TEST|LOCAL"), the departments (as described above) must be assigned to the domains of the operating system users. If departments are not assigned, login will also fail.