Drupal 8 Kerberos Integration

In this blog post, I will explain the integration of Kerberos with Drupal 8.

Burcu Binici

10 min. read

What do we want?

Active Directory (LDAP) user, password and access to the Apache server.
Drupal 8 authentication services (in our case provided by the LDAP SSO module) to retrieve the authenticated user and user information, whose username is sent to PHP as $ _SERVER ['REMOTE_USER'], group membership without checking the password and access to the Drupal 8 site with Kerberos access by Apache without asking for user and password

For this to work we need the following modules and systems:

LDAP module
LDAP SSO module
Kerberos Authentication for Apache

The LDAP module will be used to register users on our website with the LDAP user and the LDAP SSO module will be used for authentication with Apache over Kerberos.

About Kerberos

Kerberos is a network authentication system that relies on a trusted third party. The other two parties are the user and the service the user wants to connect to. Not all services and applications can use Kerberos, but for those services and applications that can, Kerberos provides (single sign on) access to the network.

In this section, we will set up and configure the Kerberos server and some user settings.

Summary

If you are new to Kerberos, there are some words you need to understand. Many of these words may be familiar from other environments.

Principal: All users, computers, and services provided by servers must be identified as Kerberos Principals.

Instances: It is used for service managers and those who have a special administrative admin role.

Realms: The unique sphere of control provided by a Kerberos installation. Think of it as the domain or group to which your hosts and users belong. By default, ubuntu will use the capitalised DNS domain (EXAMPLE.COM) as the realm.

Key Distribution Center: (KDC) consists of three parts, a database of all principals, an authentication server and a ticket issuing server. There must be at least one KDC for each region.

Ticket Granting Ticket: Determined by the Authentication Server (AS), the Ticket Granting Ticket (TGT) is encrypted with the password of the user known only to the KDC.

Ticket Granting Server: (TGS) issues service tickets to users upon request.

Tickets: It authenticates two principals. One is a principal, the other a service requested by the user. The tickets generate an encryption key used for secure communication during the authenticated session.

Keytab Files: Keytab are files extracted from the KDC main database and contain the encryption key for a service or host.

In summary, Realm has at least one KDC containing the database of Principals on demand. When the Principal user connects to the server with Kerberos access, the KDC issues a Ticket Granting Ticket (TGT). If the credentials provided by the user match, they are authenticated and the Ticket Granting Server (TGS) requests tickets from the server for the Kerberos configured service. Ticket services authenticate the user without asking the user to verify their username and password again.

Kerberos Authentication for Apache

Kerberos is a computer network authentication protocol that works on the basis of tickets to allow nodes communicating over an insecure network to securely prove their identity to each other. The protocol was named after the character Kerberos (or Cerberus) from Greek mythology, the ferocious three-headed guard dog of Hades.

Its designers primarily targeted the user-server model and provide mutual authentication, with both user and server authenticating each other. Kerberos protocol messages are protected against eavesdropping and replay attacks.

Kerberos is based on symmetric key encryption and requires a trusted third party. Optionally, it can use public key encryption in certain authentication phases. Kerberos uses UDP port 88 by default.

For these reasons, Kerberos is a viable option for Apache authentication.

Settings

We will make Kerberos settings for Apache via Ubuntu.

Prerequisites

The system clock of the servers and user services connected to the Kerberos realm must be compatible with each other. In our case, the system clocks of the Windows server hosting the users, i.e. the LDAP server, and the Ubuntu server hosting the Apache server must be synchronised (there must be a maximum of 5 minutes difference for Kerberos to work correctly). Also, your website must have a valid domain name, Kerberos authentication does not work with IP addresses. If you are on localhost, you can define the domain name in your /etc/hosts file. For example: 127.0.0.1 apache.drupart.local

Clock Synchronisation

To synchronise the system time of the Ubuntu server with the system time of the LDAP server, you can use NTP, which runs on the command line. To install NTP, run the following command:

sudo apt-get install ntp

Restart the NTP service:

sudo service ntp restart

Synchronise the server's system clock with the following command

sudo ntpdate -s drupal.drupart.local

Kerberos Settings

Install libapache2-mod-auth-curb and krb5-user using the following command:

sudo apt-get install libapache2-mod-auth-kerb krb5-user

We will use libapache2-mod-auth-kerb to connect Apache with Kerberos. krb5-user is not a real requirement, but it provides useful command-line tools for Kerberos.

In addition to the libapache2-mod-auth-curb command, krb5-config installs the dependency package and then shows a configuration wizard prompting for

Default Kerberos version 5 realm. Use DRUPAL.LOCAL (in capital letters).
KDC.My Active Directory server is drupal.drupart.local, change it to your own server.
Administration server. This is usually the same as the LDAP/Active Directory server, or in the case of multiple domain controllers, should normally be set to the host.

[libdefaults]
   default_realm = DRUPART.LOCAL # Active Directory Domain
# The following krb5.conf variables are only for MIT Kerberos.
   kdc_timesync = 1
   ccache_type = 4
   forwardable = true
   proxiable = true

# The following encryption type specification will be used by MIT Kerberos
# if uncommented.  In general, the defaults in the MIT Kerberos code are
# correct and overriding these specifications only serves to disable new
# encryption types as they are added, creating interoperability problems.
#
# The only time when you might need to uncomment these lines and change
# the enctypes is if you have local software that will break on ticket
# caches containing ticket encryption types it doesn't know about (such as
# old versions of Sun Java).
#   default_tgs_enctypes = des3-hmac-sha1
#   default_tkt_enctypes = des3-hmac-sha1
#   permitted_enctypes = des3-hmac-sha1
# The following libdefaults parameters are only for Heimdal Kerberos.
   fcc-mit-ticketflags = true
[realms]
   DRUPART.LOCAL = {
       kdc = drupal.drupart.local # Active Directory domain controller.
       admin_server = drupal.drupart.local
   }
[domain_realm]
   .drupart.local = DRUPART.LOCAL
   drupart.local = DRUPART.LOCAL

To make sure Kerberos is working, ping your Windows server. For example; ping drupal.drupart.local.
There must be a user in the Windows Domain DRUPART.LOCAL. In this example, hakan is used as the username.
On the command line:

kinit [email protected]

You will be asked for a password.

Write klist at the terminal to see the first ticket we received from KDC.

$ klist
Default principal: [email protected]
Valid starting    Expires           Service principal
25/02/2019 13:12  26/02/2019 23:11  krbtgt/[email protected]
       renew until 25/02/2019 13:12

Let's map user Hakan to HTTP/[email protected] princıpal with the following command:

C:\>ktpass
-prince HTTP/[email protected]
-mapuser [email protected]
-crypto RC4-HMAC-NT
-ptype KRB5_NT_PRINCIPAL
-pass 1234567
-out C:\intranetkeytab

This command creates an intranetkeytab file in C: \ creates an intranetkeytab file. Copy this file and put it in the /etc/apache2/ folder as http_intranet.keytab on the Apache server. Make sure everything is configured correctly with the following commands:

$ kvno HTTP/[email protected]
HTTP/[email protected]: kvno = 4
$ klist -e
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: HTTP/[email protected]
Valid starting    Expires           Service principal
25/02/2019 14:53  25/02/2019 00:52  krbtgt/[email protected]
       renew until 26/02/2019 14:53, Etype (skey, tkt): aes256-cts-hmac-sha1-96, ...
25/02/20194 15:09  25/02/2019 00:52  HTTP/[email protected]
       renew until 26/02/2019 14:53, Etype (skey, tkt): arcfour-hmac, arcfour-hmac
$ klist -e -k -t /etc/apache2/http_intranet.keytab
Keytab name: FILE:http_intranet.keytab
KVNO Timestamp        Principal
---- ---------------- ---------------------------------------------------------
  4 01/01/1970 01:00 HTTP/[email protected] (aes256-cts-hmac-sha1-96)

Trying to use the service to authenticate as a principal, check that the key is correctly added to the key tab, then view the ticket provided:

$ kinit -k -t /etc/apache2/http_intranet.keytab HTTP/[email protected]
$ klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: HTTP/[email protected]
Valid starting    Expires           Service principal
25/02/2019 14:11 25/02/2019 00:10  krbtgt/[email protected]
       renew until 26/02/2019 14:11
Configure Apache for Kerberos Authentication

Apache must be told which parts of which web sites are to use authentication provided by mod_auth_kerb. This is done using the AuthType directive with a value of Kerberos.

In order to specify which Kerberos authentication add following snippet to your virtual host configuration:

<VirtualHost *:80>
   ServerAdmin webmaster@localhost
   DocumentRoot /var/www/html/web
   ServerName apache.drupart.local
   <Location /user/login/sso> # /user/login/sso is required for Drupal LDAP SSO module
       AuthType Kerberos
       AuthName "Kerberos authenticated intranet"
       KrbAuthRealms DRUPART.LOCAL
       Krb5Keytab /etc/apache2/http_intranet.keytab
       KrbServiceName Any
       KrbMethodNegotiate on
   KrbMethodK5Passwd on        
   KrbSaveCredentials on
       KrbVerifyKDC on
       Require valid-user
   </Location>
   ErrorLog ${APACHE_LOG_DIR}/error.log
   CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

The last step is to reload the apache settings:

sudo service apache2 force-reload

When you visit apache.drupal.local/user/login/sso, if your LDAP and LDAP SSO modules are configured, you will be authenticated without asking for username and password.

Drupal LDAP and LDAP SSO Settings

Since this blog is about Kerberos authentication, you can find articles about Drupal LDAP module settings online. On the other hand, LDAP SSO settings are simple. From now on I will assume that the Drupal LDAP module is properly set up and working.

Install the LDAP SSO module with composer:

composer require 'drupal/ldap_sso:^1.0'

After installing the LDAP SSO module, go to /admin/config/people/ldap/sso and check the following values:

Turn on automated single sign-on

Automatically logs in when Drupal is opened.

Split user name and realm

If your users are shown as user@realm, you need to enable this. This is the default for mod_auth_kerb but not mod_auth_sspi.

Also, the value for the Server variable containing the user must be 'REMOTE_USER'. Then uncheck 'Redirect users on logout', as you will try to log in automatically when we log out.

If everything is OK, when we log in to our Drupal website we will be automatically logged in without asking for any user/password.