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.
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).
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.
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 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.
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.
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.
For the SSO Agent to authenticate users using Kerberos, all of the following must be true:
- The agent must be running and the host it is running on must have a name which is known to the client machines.
- The agent must be able to authenticate itself with the Kerberos controller
- 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.
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:
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.
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.
The SSO Agent documentation explains how to set the LDAP user name and password and how to set a separate Kerberos user name and password if required.
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 SSO Agent documentation.
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
-S option shown ensures that no other user name has been associated with the SPN.
Clients fail to authenticate in ITRS applications
- Check application logs.
- Check whether testuser endpoint works.
- If testuser endpoint works, check that user has LDAP groups expected by applications.
Browser falls to authenticate using testuser endpoint
- Check that status page is available.
- Check agent console output and log.
Status page not available
- Check agent is running.
- Check firewall.
Agent reports error reading Kerberos message
- Check that agent is using correct credentials to connect to Kerberos
Agent log reports that client is attempting NTLM authentication
If you see an error message in the form
ERROR com.itrsgroup.ssoagent.authentication - Client is attempting NTLM authentication. There is a configuration issue.:
- Check that SPN is set up correctly.
- Check that CNAME records do not cause host name in SPN to be different from URL.
Agent log reports that it cannot verify Kerberos credential because realm is not as expected
If you see a warning message in the form
WARNING com.itrsgroup.ssoagent.authentication - Cannot verify Kerberos credential: realm='xxx', expected='yyy':
- Consider changing kerberos.realm_mismatch setting.