Enabling single sign-on (SSO) for the AWI

Document created by Michael_Lowry on Jan 8, 2019
Version 1Show Document
  • View in full screen mode

Introduction

UC4 v11 introduced the ability to integrate the UC4 GUI into the OS so that once the user has authenticated with the OS, he does not need to enter his user ID and password again in the UC4 GUI. This feature, called single sign-on (or integrated authentication), requires some additional configuration before it will work. Specifically, the Automation Engine server must run at least once of the new Java Work Processes (JWP). The JWP uses Kerberos to authenticate users with a Kerberos Domain Controller. (In most customer environments, the KDC is a Microsoft Active Directory server. In the rest of this document, I will use the terms KDC and AD interchangeably.)

 

Service users, service principal names, etc.

Each program that authenticates with the KDC must identify itself using a Service Principal Name or SPN. The Automic Web Interface (AWI) needs its own SPN for this purpose, so that the KDC accepts the connection. The AWI authenticates with the Kerberos Domain Controller (KDC) using a keytab file. The keytab file contains the Kerberos key(s) that the application uses to authenticate itself to the KDC. There must be a one-to-one relationship between this SPN and a service user. In other words, each SPN used by the Automic Web Interface must have its own dedicated user in Active Directory.

 

The basic steps for setting up the Kerberos side of things look like this:

  1. Create a service user* in the KDC (e.g., Active Directory).
  2. Create a service principal name (SPN) with service name HTTP,  linking the above service user to the and the host name of the AWI server.
  3. Create a keytab containing the correct key for this SPN.

 

* Service users are sometimes also called technical or non-personal users. They are users used only by services and programs. Under normal conditions, it will not be necessary for a person to log in as a service user.

 

Create a service user for the AWI

An Active Directory administrator should be able to perform this action.

In this example, the service user is called UC4EXP1.

 

Create a service principal name for the AWI

An Active Directory administrator should be able to perform this action.

In this example, the service principal name created for the AWI is HTTP/awi-exp.mycompany.com.

 

List SPN information

From the Windows command line, confirm that the SPN can be found in Active Directory.

C:\>setspn -L UC4EXP1
Registered ServicePrincipalNames for CN=UC4EXP1,OU=TechUser,DC=corp,DC=mycompany,DC=com:
HTTP/awi-exp.mycompany.com.com

 

Also confirm that exactly one user is associated with the SPN.

C:\>setspn -Q HTTP/awi-exp.mycompany.com.com

Checking domain DC=corp,DC=mycompany,DC=com

CN=UC4EXP1,OU=TechUser,DC=corp,DC=mycompany,DC=com

        HTTP/awi-exp.mycompany.com.com

Existing SPN found!

 

Create a Kerberos keytab file

The official CA Automic instructions for setting up single sign-on is written based on the assumption that the person setting things up will have AD Domain Administrator access. We know this because the options indicated in the ktpass command in the section Generate keytab file on the AWI server are options that only a domain admin is authorized to use. If you have domain admin rights, you can follow the keytab creation instructions in that document, and then skip ahead here to the section Validate the keytab. The instructions below are written based on the assumption that you do not have domain admin access.

 

Determine the kvno & salt of an SPN

The kvno and salt are two pieces of information that are required when generating a keytab file. Each SPN has its own salt and kvno. The kvno is the key version number. Each time a new key is generated for a user in the KDC, the kvno is incremented in the KDC. Any keytabs created for this user must have the same kvno as the one associated with the SPN/user in KDC/AD.

The salt is a piece of information used to introduce pseudo-randomness into the keys. It is stored in the KDC and updated each time the ktpass.exe command is used with the +mapuser option.

The salt is derived from:

  • The realm in all uppercase letters, and
  • The most recent userPrincipalName (UPN) set using ktpass.exe.  

Because the salt is not always straightforward to guess, it may be necessary to run a packet trace to discover it. The salt will be used later during creation of the keytab.

 

Extract the salt from a packet trace

To find out the salt you will need to use when creating the keytab, you must capture a packet trace of a kinit session, and examine this packet trace using WireShark.

 

Capture a packet trace of a kinit using tcpdump

You will need to run the tcpdump on a Linux box where you have root access.

# /usr/sbin/tcpdump -s 0 -w /tmp/krb_uc4exp1.pcap -i eth0 tcp port 88
tcpdump: listening on eth0, link-type EN10MB (Ethernet), capture size 65535 bytes

While the tcpdump is running, in another screen/window, run kinit as the user whose salt you want to capture.

$ kinit uc4exp1
Password for
uc4exp1@CORP.MYCOMPANY.COM:
$ klist -e
Ticket cache:
FILE:/tmp/krb5cc_11041
Default principal: uc4exp1
@CORP.MYCOMPANY.COM

Valid starting     Expires            Service principal

02/10/1714:01:4802/11/1700:01:58krbtgt/CORP.MYCOMPANY.COM@CORP.MYCOMPANY.COM
renew until 02/11/17 14:01:48, Etype (skey, tkt): AES-256 CTS mode with 96-bit SHA-1 HMAC, AES-256 CTS mode with 96-bit SHA-1 HMAC Kerberos 4 ticket cache: /tmp/tkt11041

klist: You have no tickets cached

Enter the user’s password, if optionally list the TGT by running klist. Then switch batch to the screen/window running the tcpdump, and type Ctrl-C to cancel it. Transfer the file (uc4exp1.pcap in this example) to a Windows PC and open it in WireShark.

 

Examine the kinit packet trace in WireShark

Look at the KRB5 AS-REP packet. Expand the Kerberos section to reveal the salt. There, you can also see the kvno.

The salt and kvno of the user UC4EXP1, as seen in a packet trace of a kinit as this user, viewed in WireShark. In this example, the salt was CORP.MYCOMPANY.COMUC4EXP1, the realm name followed immediately by the user name. Again though, the salt may not always follow this pattern. The above method is the only 100% reliable way I have found to discover the salt of SPN that must be used when creating the keytab.

 

Show the kvno of an SPN from the Linux command line

It is also possible to reveal the kvno of an SPN from the Linux command line. Authenticate using kinit (as your user or any user), and then use the kvno command to show the kvno of an SPN.

$ kinit

Password for myuser@CORP.MYCOMPANY.COM:

$ /usr/lib/mit/bin/kvno HTTP/awi-exp.mycompany.com

HTTP/awi-exp.mycompany.com@CORP.MYCOMPANY.COM: kvno = 2

Create the keytab

The keytab should contain all three keys that will be needed: 1 for each AE node, and a third for the AWI. These commands must be run on Windows, because the equivalent ktutil command on Linux lacks the /rawsalt option. This command must be run on a Windows system where you have Administrator access.

ktpass.exe /out c:\temp\AE_EXP.keytab /princ HTTP/awi-exp.mycompany.com@CORP.MYCOMPANY.COM /pass XXXXXXXX
/kvno 2 /crypto AES256-SHA1 /pType KRB5_NT_PRINCIPAL /rawsalt CORP.MYCOMPANY.COMUC4EXP1 -setupn

In the command above, ****** represents the UC4EXP1 user's AD password.

Note: As described in Microsoft’s ktpass documentation, the -setupn option prevents updating the userPrincipalName in AD.

 

Validate the keytab

Once you have successfully created the keytab, you should validate it.

 

List the keys in the keytab

You can list the keys in the keytab file (there should be only one key) using the klist command.

$ klist -eKk AE_EXP.keytab
Keytab name: FILE:AE_EXP.keytab
KVNO Principal
---- --------------------------------------------------------------------------
2
HTTP/awi-exp.mycompany.com@CORP.MYCOMPANY.COM(AES-256 CTS mode with 96-bit SHA-1 HMAC)
(0x108c5fc7e3861bc219d2e9e086cbe4648b1a2ff2c0a8c0cd24ec4ca100f32fcb)

Validate the format of the key in the keytab

You can validate the format of the key in the keytab using the kvno command.

$ /usr/lib/mit/bin/kvno -k /opt/uc4/server/AE_EXP.keytab AE_EXP/ae-exp-1.mycompany.com
AE_EXP/ae-exp-1.mycompany.com@CORP.MYCOMPANY.COM: kvno = 2, keytab entry valid

 

Test authenticating with the KDC using the keytab

Once you know that the keytab contains a key, and that the key is in a valid format, you can try authenticating with the KDC using the keytab. Because the authentication is performed using the key stored in the keytab, you should not need to enter a password.

$ kinit -kVt AE_EXP.keytab -S AE_EXP/ae-exp-1.mycompany.com AE_EXP/ae-exp-1.mycompany.com
Authenticated to Kerberos v5
$ klist Ticket cache: FILE:/tmp/krb5cc_11041
Default principal: AE_EXP/ae-exp-1.mycompany.com@CORP.MYCOMPANY.COM

Valid starting     Expires            Service principal
03/10/16 13:34:15  03/10/16 23:34:15  AE_EXP/ae-exp-1.mycompany.com

renew until 03/11/16 13:34:15
Kerberos 4 ticket cache: /tmp/tkt11041
klist: You have no tickets cached
$ /usr/lib/mit/bin/kdestroy

Note: If the userPrincipalName of the user in Active Directory is not set to the same thing as the servicePrincipalName, the above method of validating the keytab will not work, and will return an error even if the key is valid:

kinit(v5): Client not found in Kerberos database while getting initial credentials

The reason is the kinit expects userPrincipalName to be set to exactly the same thing as servicePrincipalName in Active Directory. If you want to be able to use kinit to validate the key, you must set userPrincipalName for the service user to the same thing as servicePrincipalName in Active Directory.

If all goes well, the text in bold above will appear, confirming that the user could be authenticated with the domain controller using the key in the keytab. If the following error appears, it means that authentication failed.

kinit(v5): Client not found in Kerberos database while getting initial credentials

If this happens, the reason could be an invalid password, an incorrect salt, or a problem with the KDC.

 

Configure AE server to enable single sign-on.

Install the keytab on the AE server

In this example, the keytab file is installed in /opt/uc4/server/ and is called AE_EXP.keytab.

 

Configure the AE server to use Kerberos

In the above example:

  • MYCOMPANY is the department name associated with the Kerberos realm CORP.MYCOMPANY.COM.
  • HTTP/awi-exp.mycompany.com is the service principal name (SPN) created for the AWI.
  • /opt/uc4/server/AE_EXP.keytab is the keytab file created for the AWI.

Install LDAP server’s SSL cert on the AE server

$ $JAVA_HOME/java -Xmx512M -jar /opt/uc4/server/ucsrvjp.jar -installcert corp.mycompany.com:636
Loading KeyStore /opt/uc4/java/jre1.8.0_102/lib/security/cacerts...
Opening connection to corp.mycompany.com:636...
Starting SSL handshake...
One or more certificates are not trusted, they will be imported now.
Server sent 2 certificate(s):
1 Subject CN=DA0012.corp.mycompany.com Issuer CN=MyCompany CA 2, O=MyCompany, C=US
2 Subject CN=MyCompany System CA 2, O=MyCompany, C=US Issuer CN=MyCompany Root CA 1, O=MyCompany, C=US
Successfully added 2 certificate(s).

Use Oracle Java 7 or later

  • IBM Java is not supported.
  • Java version 6 and earlier are not supported.
  • On UC4_EXP, Java has been installed in the /opt/uc4/java directory.
  • Or get a Oracle Java here:

Get Oracle JDBC drivers and put them in the AE lib directory

  • Get the right version of OJDBC for the Java version, e.g., ojdbc7.jar for Java 7.
  • Copy the OJDBC JAR files to the Automation Engine server lib directory /opt/uc4/server/lib

    $ ls -l /opt/uc4/server/lib
    total 19244
    drwx------ 2 uc4 staff 4096 Jul 15 11:40 ./
    drwxr-x--x 5 uc4 staff 4096 Jul 15 11:38 ../
    -rw-r--r-- 1 uc4 staff 5419088 Jul 6 17:00 ojdbc7dms_g.jar
    -rw-r--r-- 1 uc4 staff 4044963 Jul 6 17:00 ojdbc7dms.jar
    -rw-r--r-- 1 uc4 staff 5395834 Jul 6 17:00 ojdbc7_g.jar
    -rw-r--r-- 1 uc4 staff 3397734 Jul 6 17:00 ojdbc7.jar
    -rwx------ 1 uc4 staff 1388670 Mar 24 11:16 org.eclipse.osgi_3.9.0.v20130529-1710.jar*

     

  • If the JAR files are not present or cannot be read, you will see an error like this in the JWP log file:

    20150706/145413.471 - U00003492 Server has been started on Host 'ae_exp' ('10.51.20.198') with process ID '29646'.
    20150706/145413.471 - U02000071 Current directory: /opt/uc4/server
    20150706/145413.472 - U00011849 UC4_sys_info: 'UC4 Version 11.1.0+hf.1.build.1018'
    20150706/145413.472 - U00011849 UC4_sys_info: 'BuildTimestamp 2015-03-24 10:07:45'
    20150706/145413.472 - U00011849 UC4_sys_info: 'Buildnr: 0000001018 Changelist: 0006505053'
    20150706/145413.823 - U00003545 UCUDB: Opening database ...
    20150706/145413.906 - U00003611 DB OPEN executed. Return Code = '0'
    20150706/145413.907 - U00003590 UCUDB - DB error: '08001', 'No suitable driver found for jdbc:oracle:thin:@//ORAX1.MYCOMPANY.COM:1521/X450.MYCOMPANY.COM', '0', 'java.sql.SQLException'
    20150706/145413.913 - U00003432 Termination of Server 'UC4_EXP#WP' initiated.
    20150706/145413.919 - U00003410 Server 'UC4_EXP#WP' version '11.1.0+hf.1.build.1018' ended abnormally.

     

Install JCE Unlimited Strength

  1. AE Server: Put the JAR files in $JAVA_HOME/lib/security and restart the JWP.
  2. GUI: Put the JAR files in %JAVA_HOME%\lib\security and restart the UC4 GUI.

If you see this error, then something went wrong (either the JCE jars were not loaded correctly, or you have the wrong version of Java (See above about using Oracle Java, not IBM Java).

20150706/170032.526 - U00045003 Java Cryptography Extension (JCE) Unlimited Strength is not installed.

Enable Java Kerberos tracing

If you encounter problems, you can sometimes learn more by enabling debug Kerberos information in Java. To do this,  add the following to the command that starts the java process (the JWP, the AWI, or both):

-Dsun.security.krb5.debug=true

Note that the additional debugging messages will be sent to standard output, and will not be displayed or logged if the JWP is started via the UC4 Service Manager. In order to see these messages, you must start the JWP from the command line.

 

Install krb5.conf file

Java should be able pick up the necessary details of the Kerberos environment from the OS. However, it’s often best to make sure that Java gets the correct information, either by specifying the details in system properties at runtime, or by specifying them in a krb5.conf file in $JAVA_HOME/lib/security. The path to the file can be set using the KREB5_CONFIG environment variable. See the MIT Kerberos documentation for more details.

[libdefaults]
default_realm = CORP.MYCOMPANY.COM
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
default_checksum=rsa-md5
udp_preference_limit = 1
udp_preference_list = 1 kdc_timeout=60000
forwardable = true
proxiable = false
renewable = true
dns_canonicalize_hostname = true
rdns = false
[realms]
CORP.MYCOMPANY.COM =
{
kdc = ldap.mycompany.com:88
default_domain = corp.mycompany.com
}
[domain_realm]
.corp.mycompany.com = CORP.MYCOMPANY.COM
.mycompany.com = CORP.MYCOMPANY.COM

Additional krb5.conf options

The options below will force Kerberos to look up the long (canonical) host names, and not to do the name→IP→name lookup.

dns_canonicalize_hostname = true
rdns = false

 

Original discussion thread: Single sign-on / integrated authentication

Attachments

    Outcomes