Setting up Kerberos Authentication For ITRS SSO

Introduction to Kerberos Copied

Kerberos is an open source authentication mechanism. It has been described as “an authentication protocol for trusted hosts on untrusted networks” and has been the preferred authentication mechanism used by Microsoft operating systems from Windows 2000 onwards.

It has the following useful features:

• Single sign-on: once a user has been authenticated once (for instance by logging into a Windows domain), they do not have to do so again, even when accessing services on other computers.
• The user’s password never travels over the network, is never stored at all on the client machine and is not stored in unencrypted form even in the authentication server database.
• None of the information in the messages exchanged can be re-used to impersonate the user. (This is not true for the older Microsoft authentication mechanism, NTLM)

Kerberos works by clients requesting “tickets” from a Key Distribution Center (KDC), which is associated with an authentication service. First a client (for example, Windows running on a workstation) gets a “ticket granting ticket” (TGT) from the KDC. The Kerberos protocol allows the user to prove their identity to the authentication service and the TGT is proof that this has happened.

When a client (such as a browser) needs access to a service (such as a database or a webserver) which uses Kerberos authentication, it needs to present a ticket for that service to the server in question. To get this ticket, the client sends a request to the KDC, specifying which service it the ticket will be for and providing secret information from its TGT which proves the identity of the user.

The service ticket is encrypted using a secret shared by the KDC and the service; if the server can read the ticket, it is assured that it proves the identity of the user. If the client presents a ticket for the wrong service, the server will report that it cannot read the ticket, and not that it is invalid.

The klist command Copied

The klist command, available on both Windows and Unix, shows what tickets have been granted to the current user:

$ 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

The example above shows three tickets (out of a total of seven in the current Windows session): the Kerberos ticket-granting ticket, a ticket for a web service (which happens to be an instance of the ITRS SSO Agent) and a ticket for a CIFS service (a NAS file server).

The Server: line in each ticket shows the Kerberos “service principal name” for which the ticket was requested. It consists of a component identifying the type of service (krbtgt, HTTP or cifs) and another component which (in each case except the first) is the fully qualified domain name (FQDN) of the machine providing the service.

Summary Copied

It is important to note from the overview above that:

• Each service using Kerberos to authenticate its users needs an account in the Kerberos domain.
• Client applications need to know the correct Kerberos Service Principal Name for the service in order to request a ticket.
• All service tickets granted to a user will use the identity encoded in the initial ticket-granting ticket: when using Kerberos authentication on Windows, a user can only connect to a service using the identity with which they have logged on to Windows.

ITRS Single Sign On (SSO) overview Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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.

Troubleshooting Copied