The Kerberos Protocol

Introduction

Kerberos is a network authentication protocol built to authenticate trusted hosts over open and unsecured networks. Authentication is based on the exchange of tickets between a client, a central authority - the Key Distribution Center, commonly referered to as KDC -, and a service.

At a high level, clients and services rely on the KDC as trusted third party to validate their identities. To get a better understanding of how Kerberos functions, we recommend this excellent tutorial: Kerberos Protocol Tutorial

A basic understanding of Kerberos is important for anyone working with TDP as core components are kerberized by default. Users must have a Kerberos client installed and configured on their system in order to connect with TDP services.

Terminology

The following terms are important to understand the basics of Kerberos:

• Principal: The Kerberos term for users. Can refer to nominative persons, applications or service users.
• Realm: The domain of an authentication service in which it may authenticate users. For the most part, a user and a service must belong to the same realm for authentication to work. Cross-realm authentication is possible but an advanced topic that is not covered here.
• Ticket: Pieces of information that are generated by the KDC and supplied to users. Users rely on tickets to prove their identity and gain access to services.

Client Configuration

Kerberos is configured via local files that permit administrators to specify settings on a per-machine basis. These configuration settings include the locations of KDCs and admin servers for realms of interest, default realms, mappings of hostnames onto Kerberos realms, the local credential cache location, and more.

A Kerberos configuration file may contain the following sections, among others:

• [libdefaults] - Settings used by the Kerberos V5 library
• [realms] - Realm-specific contact information and settings
• [domain_realm] - Maps server hostnames to Kerberos realms

Below is an example configuration that permits a machine to connect to the KDC deployed as part of the tdp getting started configuration:

[libdefaults]
  renew_lifetime = 7d
  forwardable = false
  default_realm = REALM.TDP
  ticket_lifetime = 24h
  dns_lookup_realm = false
  dns_lookup_kdc = true
  default_ccache_name = FILE:/tmp/krb5cc_%{uid}

[realms]
  REALM.TDP = {
    kdc = master-01.tdp
    admin_server = master-01.tdp
    kpasswd_server = master-01.tdp
 }

[domain_realm]
  .tdp = REALM.TDP

Authentication

Kerberos enables Single-Sign-On (SSO) authentication. Once a client is fully configured, users can request a Ticket Granting Ticket (TGT) from the Authentication Service (AS) hosted in the KDC. This ticket is valid for a limited duration and permits the holder to authenticate with all services that are part of the corresponding realm.

Aside from the initial ticket request this process is seamless for users.

Keytabs

Keytab is short for “key table” and refers to a piece of data - almost always a file - that holds long-term keys for one or more principals. They are primarily used by server applications to accept authentication requests from clients. Clients may also use a keytab to obtain a TGT.

This command permits authentication from a terminal if a keytab file is available on the machine:

kinit -kt path/to/keytab princial@realm

Clusters deployed with the tdp getting started configuration include a preconfigured tdp_user on the edge node. This user has access to a keytab file located at /home/tdp_user/files/keytabs. To authenticate from the tdp_user home directory without password:

kinit -kt ./files/keytabs/tdp_user.keytab tdp_user@REALM.TDP

For Linux & macOS

Users on Linux and macOS can authenticate with Kerberos via a terminal.

Installation on Linux & macOS

Kerberos is pre-installed on macOS and most modern Linux distributions. If not, a Kerberos client is available from many package managers. For example:

sudo apt update && sudo apt install krb5-user

As you install the client, you are prompted to set a default realm name. Note that this may be changed later. If you install Kerberos to use with the tdp getting started configuration, choose REALM.TDP.

Configuration on Linux & macOS

By default, the local configuration file is located at /etc/krb5.conf. Depending on your setup and the KDC you want to connect to, you may not need to make any modifications. If you want to connect to a realm via a KDC that is not discoverable via DNS, do the following:

1. Add the realm information to your krb5.conf file:

[realms]
REALM = {
  kdc = host.domain
  admin_server = host.domain
}

[domain_realm]
  .domain = REALM

To connect to a tdp getting started realm, add the following:

[realms]
REALM.TDP = {
  kdc = master-01.tdp
  admin_server = master-01.tdp
}

[domain_realm]
  .tdp = REALM.TDP

2. Add the domain of your KDC to your local /etc/hosts file:

# IP address      # Address
xxx.xxx.xxx.xxx   host.domain      # Optional comment

To connect to a tdp getting started cluster:

# Added for TDP getting started cluster
192.168.56.10 edge-01.tdp
192.168.56.11 master-01.tdp
192.168.56.12 master-02.tdp
192.168.56.13 master-03.tdp
192.168.56.14 worker-01.tdp
192.168.56.15 worker-02.tdp
192.168.56.16 worker-03.tdp
# End of entry

Authentication on Linux & macOS

Once your Kerberos client is configured, authenticate with the following command:

kinit principal@realm 

Note that @REALM is not required if the realm you want to connect to is configured as default_realm in krb5.conf.

View your existing tickets:

klist 

To authenticate with a tdp getting started cluster using the preconfigured tdp_user and the default password:

# Request a ticket 
echo tdp_user123 | kinit tdp_user@REALM.TDP 

# Confirm your ticket was granted
klist

# Expected output:
#   
#   Ticket cache: FILE:/tmp/krb5cc_1000
#   Default principal: tdp_user@REALM.TDP
#   
#   Valid starting       Expires              Service principal
#   dd/MM/yyyy hh:mm:ss  dd/MM/yyyy hh:mm:ss  krbtgt/REALM.TDP@REALM.TDP

For Windows

A graphical user interface to authenticate with Kerberos is avalable on Windows. The following instructions apply to Windows 10 and 11.

Installation on Windows

Download and install the current “Kerberos for Widnows Release” from the MIT Kerberos Distribution Page and install it on your system. The installation is straightforward and the default settings are sufficient. Note that a restart is recommended by the installer but - in our experience - not necessary.

Configuration on Windows

Before the Kerberos client can connect to a KDC, a credentials cache has to be configured. On a Windows system, this is either an environment variable or a profile variable in a configuration file:

We use the placeholder {username} in this section to refer to your local Windows user. Be sure to replace it with your actual Windows user name to execute any of the commands. If you are not sure what your user name is, open a PowerShell session and type whoami. This produces the response {hostname}/{username}.

To define your credential cache through an environment variable:

• Open your start menu and type “environment variables” until you see the option “Edit the system environment variables”.
• Select this option and click “Environment variables” in the dialog box that appears.
• Click the upper “New” button to add a new user variable named KRB5CCNAME with the value C:\Users\{username}\AppData\Local\Temp\krb5cache.

To define your credential cache in the local client configuration file:

• Grant your current user permission to modify krb5.ini (administrator privileges are required):

  • Navigate to C:\ProgramData\MIT\Kerberos5 (you may need to enable “Show hidden files” in your file explorer)

  • Right-click on the file krb5.ini and select “Properties”

  • Navigate to the “Security” tab and click “Edit”

  • Select your current user and tick the “Allow” boxes for “Full control”, Modify” and “Write”

  • Apply your changes

    

• Add the following line to krb5.ini:

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

Depending on your setup and the KDC you want to connect to, this might be all configuration that is required. If you, however, want to connect to KDCs and/or to hosts that are not discoverable via DNS, add the following configurations:

• Add the domains of the KDC and the admin server and optionally specify the domain_realm in krb5.ini.

  [realms]
  REALM = {
    kdc = host.domain
    admin_server = host.domain
  }
  
  [domain_realm]
    .domain = REALM
  

  For example, to connect with the KDC on a a tdp getting started cluster, add:

  [realms]
  REALM.TDP = {
    kdc = master-01.tdp
    admin_server = master-01.tdp
  }
  
  [domain_realm]
    .tdp = REALM.TDP
  

• Add the address of your KDC and servers to your local hosts file, located at C:\Windows\System32\Drivers\etc\hosts. Grant yourself permission to modify the file as described above, then add your hosts line by line:

  # IP address      # Address
  xxx.xxx.xxx.xxx   host1.domain      # Optional comment
  xxx.xxx.xxx.xxx   host2.domain      # Optional comment
  

  For example, if you intend to connect to a tdp cluster created with the getting started configuration, add:

  # Added for TDP getting started cluster
  192.168.56.10 edge-01.tdp
  192.168.56.11 master-01.tdp
  192.168.56.12 master-02.tdp
  192.168.56.13 master-03.tdp
  192.168.56.14 worker-01.tdp
  192.168.56.15 worker-02.tdp
  192.168.56.16 worker-03.tdp
  # End of entry
  

Authentication on Windows

To generate a ticket with Kerberos, use the “MIT Kerberos Ticket Manager” application. Note that if the KDC and all hosts are discoverable via DNS lookup from your current system, no modifications to the krb5.ini and hosts files are required. It is sufficient to include the realm name with your principal: principal@realm.

If successful, you see your ticket and additional information in the ticket manager application:

Configure your browser

As mentioned above, Kerberos enables Single-Sign-On (SSO). This also applies to browser sessions, provided your browser is configured to support the SPNEGO protocol. This is useful in situations where a kerberized service exposes web interfaces.

As an example, a tdp getting started cluster exposes several interfaces:

In order to access these, three conditions must be met:

1. You must have a valid Kerberos ticket on your system
2. The appropriate security certificates must be installed
3. Your browser must be configured for SPNEGO

Configure Firefox

If necessary, add the required security certificates to your browser:

1. Navigate to “Settings” > “Privacy and Security”
2. Scroll down to “Certificates” and click “View Certificates”
3. Click on “Authorities” and then “Import” to add the certificate

Configure the URI(s) of the sites you want to permit SPNEGO authentication for:

• In your Firefox browser, navigate to about:config

• A warning is displayed. Accept the risk to continue.

• Add or modify the following parameter: network.negotiate-auth.trusted-uris: URI

  To permit SPNEGO authentication with tdp getting started resources, add network.negotiate-auth.trusted-uris: .tdp.

  

  On a Windows system, you also need to set the following option:

  • network.auth.use-sspi: false

Configure Chrome

If necessary, add the required security certificates to your browser:

1. Navigate to “Settings” > “Privacy and Security”
2. Select “Security” and scroll down to “Manage certificates”
3. In the “Manage certificates” menu, select “Authorities” and click “Import” to add the certificate

A Chromium based browser should detect Kerberized services and the local credential cache automatically. If not, launch your browser with the --auth-server-whitelist="URI" parameter to enable access to the desired services.

To permit SPNEGO authentication with tdp getting started on a Windows machine using Chrome, open PowerShell and launch Chrome with the following command:

C:\Program Files (x86)\Google\Chrome\Application\chrome.exe --auth-server-whitelist="*.tdp"

Configure Safari on macOS

If necessary, add the required security certificates to your system:

1. Click “Applications” and select “Utilities”, then “Keychain Access”
2. In “Keychains” select “Logins”
3. Drag the certificate onto the Keychain Access app

Once a valid certificate is installed, no further configuration should be necessary.