Setting up Kerberos Authentication For ITRS SSO

$ klist

Current LogonId is 0:0x51fe5

Cached Tickets: (7)

#0>    	Client: jdoe @ EMEA.ITRS
		Server: krbtgt/EMEA.ITRS @ EMEA.ITRS
		KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
		Ticket Flags 0x40e00000 -> forwardable renewable initial pre_authent
		Start Time: 3/14/2018 8:45:13 (local)
		End Time:   3/14/2018 18:45:13 (local)
		Renew Time: 3/21/2018 8:45:13 (local)
		Session Key Type: RSADSI RC4-HMAC(NT)
		Cache Flags: 0x1 -> PRIMARY
		Kdc Called: corsvr01.emea.itrs

#1>     	Client: jdoe @ EMEA.ITRS
		Server: HTTP/mwserver.emea.itrs @ EMEA.ITRS
		KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
		Ticket Flags 0x40a00000 -> forwardable renewable pre_authent
		Start Time: 3/14/2018 8:50:50 (local)
		End Time:   3/14/2018 18:45:13 (local)
		Renew Time: 3/21/2018 8:45:13 (local)
		Session Key Type: RSADSI RC4-HMAC(NT)
		Cache Flags: 0
		Kdc Called: corsvr01.emea.itrs

#2>  		Client: jdoe @ EMEA.ITRS
		Server: cifs/nas01.emea.itrs @ EMEA.ITRS
		KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
		Ticket Flags 0x40a00000 -> forwardable renewable pre_authent
		Start Time: 3/14/2018 8:46:21 (local)
		End Time:   3/14/2018 18:45:13 (local)
		Renew Time: 3/21/2018 8:45:13 (local)
		Session Key Type: RSADSI RC4-HMAC(NT)
		Cache Flags: 0
		Kdc Called: corsvr01.emea.itrs														

ITRS Single Sign On (SSO) overview

ITRS Single Sign On is a mechanism which uses JSON Web Tokens and asymmetric (public key) cryptography to authorise and authenticate users to ITRS components such as Geneos Gateways, Webslinger instances and Web Dashboards.

Tokens are issued by the ITRS SSO Agent and signed by it using a private key. The ITRS components use the corresponding public key to check the signature, which proves that the ticket has been issued by the agent and that its contents have not been altered.

Responsibilities of the SSO Agent

The ITRS SSO Agent is implemented as a web service. It is responsible for verifying the identity of the user (authentication) and for finding out what roles the user has been granted (authorisation).

For the authorisation part, the agent uses LDAP: once it has authenticated a user, it queries an LDAP server to find out what groups the user is a member of. ITRS components treat the names of LDAP groups as the names of roles to which the user has access.

For the authentication part, the agent supports HTTP “Basic” authentication as well as Kerberos. This is mainly useful for checking the operation of the authorisation part: it is much easier to switch between test users with different roles using basic authentication than using Kerberos.

Other ITRS components

ITRS components obtain tokens from the agent in various ways:

• Active Console 2 uses an embedded HTTP client to connect to the agent’s authentication endpoint. It presents the token it obtains to the Gateway to authorize the user.
• Webslinger and Web Dashboard use HTTP redirection to instruct the user’s web browser to visit special endpoints provide by the agent.
• Gateway can redirect a REST client to the agent’s authentication endpoint to obtain a token that can be used to authorize REST requests.

Because the result of the authentication and authorisation process is encoded in a JSON web token, there is no need for the other ITRS components to know which mechanisms have been used.

Enable Kerberos for the SSO Agent

For the SSO Agent to authenticate users using Kerberos, all of the following must be true:

1. The agent must be running and the host it is running on must have a name which is known to the client machines.
2. The agent must be able to authenticate itself with the Kerberos controller
3. The agent’s Kerberos service principal name must be associated with the credentials used by the agent

The following sections expand on each of these points.

The Agent must be running

As noted above, the SSO Agent is a web service. It provides a /status endpoint which can be used to check that the agent is running and can be reached by browsers running on the client machines.

When Kerberos authentication is used, the fully qualified domain name (FQDN) of the machine where the agent is running will be used as part of the SPN.

For example, if the agent’s status page can be reached using the following URLs:

• http://mwserver.emea.itrs:8083/status
• http://mwserver:8083/status
• http://192.168.10.221:8083/status

and assuming that mwserver.emea.itrs is the DNS reverse resolution of 192.168.10.221, then mwserver.emea.itrs is the FQDN, the name known to the client machines, for the agent’s host.

This can be checked before attempting to configure Kerberos for the agent.

The agent must be able to authenticate itself with the KDC

To authenticate with the KDC, the agent needs to be configured with credentials (username and password) with which to log on.

In most cases, the same credentials can be used to connect to the LDAP controller (for authorisation queries) and the KDC, because the LDAP controller and the KDC are usually the same domain controller and will certainly be in the same trust domain. By default, SSO Agent uses the same username and password to pre-authenticate with Kerberos that it uses to connect to the LDAP server.

The Configure SSO Agent's LDAP Settings in SSO Agent User Guide explains how to set the LDAP username and password and how to set a separate Kerberos user name and password in your sso-agent.conf if required.

Caution: The Kerberos Service Principal username may be case-sensitive. Therefore, the username specified in both the LDAP and Kerberos sections of your sso-agent.conf file should match the exact case of the username in the KDC.

The agent also needs to know the location of the KDC. It can usually determine this by looking up a DNS record for the Kerberos service:

$ dig +noall +answer srv _kerberos._tcp.emea.itrs
_kerberos._tcp.emea.itrs. 600	IN	SRV	0 100 88 srv01.emea.itrs.
_kerberos._tcp.emea.itrs. 600	IN	SRV	0 100 88 corsvr01.emea.itrs.

The Java GSSAPI module used by the agent can also be configured using the krb5.conf file, as described in the Configure Kerberos authentication in SSO Agent User Guide.

The Agent’s Kerberos service principal name must be set up correctly

As explained in the Kerberos overview above, clients using Kerberos authentication for the SSO Agent request a service ticket from the KDC using a name, called a Service Principal Name (or SPN), which they construct as follows:

• Because the agent provides a web service, the first component Is HTTP/. This is the case whether the ordinary (http://) or secure (https://) protocol is used. This component is in upper case and includes no colon and only one slash.
• The remainder of the name is the fully qualified domain name of the host where the agent is running. That is, it is the host name part of the agent’s /status URL. Note that it does not include the port.

So, if the agent’s /status URL is http://mwserver.emea.itrs:8083/status, its SPN is normally HTTP/mwserver.emea.itrs. However, if the hostname part of the URL is a name which is mapped to the actual host name of the agent by a CNAME (“canonical name lookup”) DNS record, then the SPN will contain the actual host name, not the name that appears in the URL.

If the Kerberos service is provided by Active Directory, then the agent’s SPN needs to be associated with the user name the agent uses to connect to Kerberos.

The following setspn command is used to do this:

setspn -S agent-SPN agent-username

For example, if the SPN used for the agent is HTTP/mwserver.emea.itrs and its user name is itrs_sso, then the command to issue would be:

setspn -S HTTP/mwserver.emea.itrs itrs_sso

The -S option shown ensures that no other user name has been associated with the SPN.