Adaltas Cloud Academy
Sign out >

Kerberos

Introduction

Kerberos is an authentication protocol based on the exchange of tickets. Windows 2000 and later versions use Kerberos as its default authentication method. It is often used as a Single Sign On (SSO) solution or to authenticate not only users but also computer nodes and services.

Kerberos is frequently used in complex systems. Hadoop uses it as the basis for strong authentication and identity propagation. Thus, you will need a valid Kerberos ticket to contact the majority of the services. Internally, Kerberos is also used to secure the communication between the various service which compose the platform.

Architecture

Both users and services rely on a third party - the Kerberos server - to authenticate each others. The Kerberos server itself is known as the Key Distribution Center, or KDC. At a high level, it has three parts:

  • A database of the users and services (known as principals) that it knows about and their respective Kerberos passwords
  • An Authentication Server (AS) which performs the initial authentication and issues a Ticket Granting Ticket (TGT)
  • A Ticket Granting Server (TGS) that issues subsequent service tickets based on the initial TGT

Kerberos architecture

How do you authenticate with Kerberos?

In Kerberos terminology, a user is called a principal. A principal can be a nominative person, an application user or a service user. A principal requests authentication from the AS. The AS returns a TGT that is encrypted using the user principal’s Kerberos password, which is known only to the user principal and the AS. By login or kinit program on the client, the user principal decrypts the TGT locally using its Kerberos password, and from that point forward, until the ticket expires, the user principal can use the TGT to get service tickets from the TGS.

Service tickets are what allow a principal to access various services using an RPC connection or over HTTP protocol. When the ticket is transmitted over HTTP, the communication make use of the SPNEGO protocol which store the ticket information into the HTTP header request.

How do you authenticate with Kerberos?

After authentication, servers can check an unencrypted list of recognized principals and their keys rather than checking kinit; this is kept in a special file, called a keytab, which contains the resource principal’s authentication credentials. The set of hosts, users, and services over which the Kerberos server has control is called a realm.

keytab

A keytab (short for “key table”) stores long-term keys for one or more principals. Keytabs are normally represented by files in a standard format, although in rare cases they can be represented in other ways. Keytabs are used most often to allow server applications to accept authentications from clients, but can also be used to obtain initial credentials for client applications.

A keytab contains one or more entries, where each entry consists of a timestamp (indicating when the entry was written to the keytab), a principal name, a key version number, an encryption type, and the encryption key itself. It can be displayed using the klist command:

Ticket cache: FILE:/tmp/krb5cc_1000295
Default principal: username@AU.ADALTAS.CLOUD

Valid starting     Expires            Service principal
06/04/20 21:47:56  06/05/20 21:47:56  krbtgt/AU.ADALTAS.CLOUD@AU.ADALTAS.CLOUD
renew until 06/11/20 21:47:56

Keytabs are named using the format “type”:“value”. Usually “type” is FILE and “value” is the absolute pathname of the credential cache file.

Client configuration file

Kerberos uses configuration files to allow administrators to specify settings on a per-machine basis. The “krb5.conf” file contains Kerberos configuration information, including the locations of KDCs and admin servers for the Kerberos realms of interest, defaults for the current realm and for Kerberos applications, and mappings of hostnames onto Kerberos realms. Normally, “krb5.conf” file is installed in the directory /etc. You can override the default location by setting the environment variable KRB5_CONFIG.

The “krb5.conf” file is set up in the style of a Windows INI file. Sections are headed by the section name, in square brackets. And each section contains parameters.

The “krb5.conf “file may contain the following sections:

  • [libdefaults] - Settings used by the Kerberos V5 library
  • [realms] - Realm-specific contact information and settings
  • [domain_realm] - Maps server hostnames to Kerberos realms
  • [capaths] - Authentication paths for non-hierarchical cross-realm
  • [appdefaults] - Settings used by some Kerberos V5 applications
  • [plugins] - Controls plugin module registration

The edge node of the Adaltas Cloud cluster is configured to use Kerberos authentication. Being there via SSH, you can print the content of the “krb5.conf” file using the command cat /etc/krb.conf:

[libdefaults]
  renew_lifetime = 7d
  forwardable = true
  default_realm = AU.ADALTAS.CLOUD
  ticket_lifetime = 24h
  dns_lookup_realm = false
  dns_lookup_kdc = false
  default_ccache_name = FILE:/tmp/krb5cc_%{uid}
  #default_tgs_enctypes = aes des3-cbc-sha1 rc4 des-cbc-md5
  #default_tkt_enctypes = aes des3-cbc-sha1 rc4 des-cbc-md5

[logging]
  default = FILE:/var/log/krb5kdc.log
  admin_server = FILE:/var/log/kadmind.log
  kdc = FILE:/var/log/krb5kdc.log

[realms]
  AU.ADALTAS.CLOUD = {
    admin_server = ipa1.au.adaltas.cloud
    kdc = ipa1.au.adaltas.cloud
  }

The information about each of the profile variables can be found in this documentation.

Automatic client discovery

Depending on your setup, you do not always need to modify the Kerberos client configuration. In the absence of entries in the configuration file, the KDC address can be obtained from the DNS records. This feature can be deactivated if dns_lookup_kdc is false in the client configuration file. The FreeIPA DNS service expose the following domain records:

  • _kerberos of type “TXT”, eg “AU.ADALTAS.CLOUD”
  • _kerberos-master._tcp of type “SRV”
  • _kerberos-master._udp of type “SRV”
  • _kerberos._tcp of type “SRV”
  • _kerberos._udp of type “SRV”
  • _kpasswd._tcp of type “SRV”
  • _kpasswd._udp of type “SRV”

Users of Adaltas Cloud with access to the cluster through a VPN tunnel transparently use our FreeIPA DNS server. It provides them with the auto discovery of the Kerberos server (KDS). You can check this on Linux with dig:

dig srv _kerberos._udp.au.adaltas.cloud +short
0 100 88 ipa-2.au.adaltas.cloud.
0 100 88 ipa1.au.adaltas.cloud.

As well as on Windows with nslookup:

nslookup -type=SRV _kerberos._udp.au.adaltas.cloud
Server:  ipa1.au.adaltas.cloud
Address:  10.0.0.5

_kerberos._udp.au.adaltas.cloud SRV service location:
         priority       = 0
         weight         = 100
         port           = 88
         svr hostname   = ipa1.au.adaltas.cloud
_kerberos._udp.au.adaltas.cloud SRV service location:
         priority       = 0
         weight         = 100
         port           = 88
         svr hostname   = ipa-2.au.adaltas.cloud
au.adaltas.cloud        nameserver = ipa1.au.adaltas.cloud
ipa1.au.adaltas.cloud   internet address = 10.0.0.5
ipa-2.au.adaltas.cloud  internet address = 10.0.0.9

About client installation

The client installation procedure is very easy on Linux and OSX. Most of the time, Kerberos comes pre-installed or, if not, a simple command with your favourite package manager will install the client library. Safari will work right away while Firefox and Chrome will require some adjustments easily found on the Internet. While being easy on Linux and OSX, it is a little bit more complicated on Windows. If your host is integrated with an Active Directory, a ticket is already present. However, you cannot always use it to contact a remote service secured with Kerberos, for example because it exposes a domain which is not trusted by the Active Directory. Moreover, Windows has its own way to manage the Kerberos ticket.

Using Windows Kerberos client

This section explains how to determine a credential cache, how to create a ticket with the MIT Kerberos client for Windows, how to store a ticket into its own file path and how to configure Firefox to make use of it.

1. Credential cache

Kerberos ticket are stored inside the credentials cache. There are multiple credentials cache supported on Windows:

  • FILE caches
    Simple and most portable. A simple flat file format is used to store one credential after another. This is the default on Linux and OSX.
  • API cache
    Only implemented on Windows, it communicates with a server process that holds the credentials in memory. This seems to be the default on Windows.

The default credential cache name is determined by the following:

  • The KRB5CCNAME environment variable
  • The default_ccache_name profile variable in [libdefaults] of the configuration file
  • The hardcoded default, DEFCCNAME, default to FILE:/tmp/krb5cc_%{uid} on Unix

[[info | Note about the credential cache path]] | In the procedures below, whether you choose to declare the credential cache with an environment variable or through the configuration file, don’t forget to replace {username} with your windows username. You can declare any path you wish. The path must correspond to the file where your Kerberos Ticket will be written. Its parent directory must exists with writable permissions by the user issuing the ticket.

Determining with the environment variable

Using the windows search, look for “environment variables” and select “Edit the system environment variables”. In the new window, click on the “Environment variables” button. From there, add a new user variable named KRB5CCNAME with the value C:\Users\{username}\AppData\Local\Temp\krb5cache.

Declare the KRB5CCNAME environment variable

From the PowerShell console, you can print the value of the credential cache with the command $Env:KRB5CCNAME. You do not need to restart your host to activate the environment variable but you must reload your PowerShell session if it was already opened.

Determining with the configuration file

The path to the Kerberos client configuration on Windows is C:\ProgramData\MIT\Kerberos5\krb5.ini. To set the credential cache, you only need to set the default_ccache_name profile variable.

Navigate to the C:\ProgramData\MIT\Kerberos5 and change the permission to allow the current user to edit the file.

Change permissions to the krb5.ini file

Now edit the file with your favourite code editor such as Sublime Text or Notepad++ and make it look like:

[libdefaults]
 default_ccache_name = C:\Users\{username}\AppData\Local\Temp\krb5cache

If C:\ProgramData\MIT\Kerberos5\krb5.ini does not exist, you can continue the configuration without it. However, you must include the Kerberos realm in your principal when creating the ticket, for example {username}@AU.ADALTAS.CLOUD instead of just {username}.

2. MIT Kerberos client installation

Download and install the Kerberos MIT client for Windows. The current version at the time of this writing is 4.1 and the download link is located in the section called “MIT Kerberos for Windows 4.1”.

Download the MIT Kerberos client

This installation procedure is straightforward. Just accept all the default settings and move forward. Once the installation is complete, the installer will ask to restart the computer.

Install the MIT Kerberos client

4. Ticket creation

A ticket can be created from the Kerberos client window by entering your provided principal and password. You are not required to modify the C:\ProgramData\MIT\Kerberos5\krb5.ini if you use include the Kerberos realm in your principal name, for example {username}@AU.ADALTAS.CLOUD instead of just {username}. Run the klist command on the edge node if you do not know your principal and realm name.

Create a Kerberos ticket

If successful, you shall view your ticket as well as some complimentary information such as the validation date as well as the credential cache location.

Visualize the Kerberos ticket

Note, opening the Kerberos client window to enter your Kerberos credential is not mandatory. Once Firefox is configured (see the next section), you can directly enter your destination URL and a new window will pop up asking for your principal and username.

Configuring Firefox

We have created a Kerberos ticket and we now need to configure a browser to use it. Edit the configuration window by writing about:config in the address bar.

Firefox configuration warning

Accept the risk and modify the following properties:

  • network.negotiate-auth.trusted-uris: .au.adaltas.cloud
    Lists the sites that are permitted to engage in SPNEGO authentication with the browser.

  • network.auth.use-sspi: false
    Determines whether to use SSPI or GSSAPI for Kerberos authentication. SSPI is a proprietary variant of GSSAPI with extensions and Windows-specific data types. It is the default API on Windows. GGSAPI is an IETF standard and it is used by the MIT Kerberos client we just installed and used.

Also, while not being mandatory, you can change the following variables:

  • network.negotiate-auth.delegation-uris: .au.adaltas.cloud
    Lists the sites for which the browser may delegate user authorization to the server.

  • network.negotiate-auth.using-native-gsslib: false
    Use the default GSSAPI library.

  • network.negotiate-auth.gsslib: C:\Program Files\MIT\Kerberos\bin\gssapi64.dll
    Specifies a alternate GSSAPI shared library. Modify the path to the appropriate dll depending on your host architecture (32 or 64 bits).

  • network.negotiate-auth.allow-non-fqdn: true
    Accepts service domain names instead of fully qualified domain names.

Firefox configuration negotiate

Firefox configuration SSPI

Ticket creation for Firefox

If you try to access a service URL secured with Kerberos but without a valid ticket, you will see such a page:

SPNEGO negotiation failed with 401 HTTP error

The 401 HTTP error code indicates that your browser failed to negotiate the authentication. As part of the SPNEGO protocol, the server has requested to negotiate the authentication by returning the WWW-Authenticate: Negotiate response header. However your browser couldn’t propose any suitable method. You can see this exchange with the curl command:

curl --negotiate -u: --head http://yarn-rm-1.au.adaltas.cloud:8088/cluster
HTTP/1.1 401 Authentication required
Date: Thu, 24 Oct 2019 09:57:48 GMT
Date: Thu, 24 Oct 2019 09:57:48 GMT
Pragma: no-cache
WWW-Authenticate: Negotiate
Set-Cookie: hadoop.auth=; Path=/; HttpOnly
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: text/html;charset=iso-8859-1
Content-Length: 267

The --negotiate argument tell to curl to negotiate the authentication with the remote service. The --user argument provide the required username and password which are empty in the case of Kerberos since the credential information is stored inside the local ticket.

With a valid ticket, the negotiation will succeed and your ticket will be encrypted as base64 in the second WWW-Authenticate header:

curl --negotiate -u: --head http://yarn-rm-1.au.adaltas.cloud:8088/cluster
HTTP/1.1 401 Authentication required
Date: Thu, 24 Oct 2019 09:58:17 GMT
Date: Thu, 24 Oct 2019 09:58:17 GMT
Pragma: no-cache
WWW-Authenticate: Negotiate
Set-Cookie: hadoop.auth=; Path=/; HttpOnly
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: text/html;charset=iso-8859-1
Content-Length: 267

HTTP/1.1 405 HTTP method GET is not supported by this URL
Date: Thu, 24 Oct 2019 09:58:17 GMT
Date: Thu, 24 Oct 2019 09:58:17 GMT
Pragma: no-cache
WWW-Authenticate: Negotiate oYH1MIHyoAMKAQChCwYJKoZIhvcSAQICom4EbGBqBgkqhkiG9xIBAgICAG9bMFmgAwIBBaEDAgEPok0wS6ADAgESokQEQhnlSj8cuKVGz6eBMJNi9R8ImTtdpJU4zV8N4s4EwJxpnmU0ZohrBtavGQxoXFSuuxScHcpiNVL51qEJzsoAA6x6iqNuBGxgagYJKoZIhvcSAQICAgBvWuBZoAMCAQWhAwIBD6JNMEugAwIBEqJEBEIZ5Uo/HLilRs+ngTCTYvUfCJk7XaSVOM1fDeLOBMCcaZ5lNGaIawbWrxkMaFxUrrsUnB3KYjVS+dahCc7KAAOseoo=
Set-Cookie: hadoop.auth="u=david&p=david@AU.ADALTAS.CLOUD&t=kerberos&e=1571947097972&s=Df9/vrrj4xHASRxHPdBJHOCap4Gdmvst1QCnjFXuceI="; Path=/; HttpOnly
X-Frame-Options: SAMEORIGIN
Vary: Accept-Encoding
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: text/html;charset=iso-8859-1
Content-Length: 309

And you can finally access all your Kerberos secured service without having to reenter your login credentials:

SPNEGO negotiation succeed