Setting up Single Sign-On

The following document contains detailed instructions on how to set up Single Sign-on (SSO) for the Automation EngineDiese Komponente steuert ein Automation Engine-System. Besteht aus verschiedenen Serverprozessen. system. Single Sign-on makes it possible to log in 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 log in ( Automic Web Interface) to the Automation Engine  system without having to enter login details (user, department and password). The operating system user under which the Automic Web Interface has been launched will be used for authentication.

These installationnull 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 (AWIAutomic-Produkt: Übersichtliche und einfach zu bedienende Weboberfläche, mit welcher der Zugriff auf verschiedene Funktionalitäten der Automation Engine möglich ist., 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
  AWI and JWP require access to the KDC (for example, Active DirectoryActive Directory (AD) ist der Verzeichnisdienst von Microsoft'+char(39)+ sowie der Überbegriff für identitätsbezogene Dienste für Windows-Netzwerke. in Windows). It is not sufficient for the AWI to have access to just the CP, for example.
• Supported JVM
  Currently, only Oracle Java is supported for Single Sign-on. If a component (JWP, AWI, Java API) runs in IBM Java, login will be aborted.

Installation steps for the AWI and Automation Engine

	1)	Registry key for TGT access

This step is required only if the AWI runs on Windows.

This registry key is required so that the 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 AWI runs.
• The Automation Engine (JWP) runs.

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

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 configuration file

This step can be omitted if the AWI 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 keytab 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 HostRechner, Zielsystem. 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 database.

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 VariableSpeichert oder ermittelt Werte dynamisch zur Laufzeit. Auch ein eigener Objekttyp in der Automation Engine. 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 in the 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 will not always work.

	5)	SSO configuration for web applications

In order to implement Single Sign-on for web applications (such as Automic Web Interface or Automic Release Automation"Automic Release Automation (ARA) ist eine End-to-end-Lösung für die Definition, Koordinierung, Planung von Freigabe-Prozessen und deren Automatisierung. Dies enthält auch die automatische Durchführung von Anwendungs-Deployments auf großen Serverumgebungen. [Früher ""Application Release Automation"", ""Release Manager"" und ""Deployment Manager"" genannt.]"), 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 Automic Web Interface (Tomcat) is installed.

The SPN name must also be entered in the variable UC_KDC_SETTINGS using the "HTTP" key. If several AWI/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 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 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 AWI.

Example:

The AWI 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.