Using Kerberos with Apache on Ubuntu

Yikes! This post is over a year old!
If you think it deserves a rewrite please get in touch or leave a comment.
— Thanks, Ash.

Deprecated: mb_convert_encoding(): Handling HTML entities via mbstring is deprecated; use htmlspecialchars, htmlentities, or mb_encode_numericentity/mb_decode_numericentity instead in /usr/src/wordpress/wp-content/themes/ashdavies/functions.php on line 120

Preparing Ubuntu Server

To begin with we need to install a few dependencies on the Ubuntu Server. In this tutorial, we will be using Ubuntu 20.04 but the same process applies to older versions. I’ve tested this configuration down to Ubuntu 14 but as always, your mileage may vary.

sudo apt update
sudo apt install krb5-user -y

The krb5-user package installs some basic programs like klist, kinit and a few others that allow your server to authenticate to Kerberos, change passwords, and communicate with the admin server.

Kerberos configuration

Once this package installation is complete, you now need to add your Kerberos realm to a configuration file.

You’ll need a few bits of info before you dive into editing the config. Make a note of your Active Directory Realm, and the IP Address / Hostname of your primary Active Directory Domain Controller.

The configuration file is located at /etc/krb5.conf. Open the file in your favourite text editor.

In the below example we are using ASHDAVIES.LAN as the Realm, and dc1.ashdavies.lan as the DNS Hostname of the Domain Controller.

Note that the AD Realm should always be written in UPPERCASE.

[libdefaults]
default_realm = ASHDAVIES.LAN
		 
[realms]
ASHDAVIES.LAN = {
	kdc = dc1.ashdavies.lan
	admin_server = dc1.ashdavies.lan
}

[domain_realm]
.ashdavies.lan = ASHDAVIES.LAN
ashdavies.lan = ASHDAVIES.LAN

That’s all the editing needed for now. The next step is configuring Active Directory and you’ll revisit your Ubuntu Server afterwards.

Active Directory configuration

There are a few small steps to configuring Active Directory and thankfully they are fairly straight forward. To start off, you should create a User Object in Active Directory which can be dedicated to your website authentication service.

In the next few examples, we’ll refer to our user as ApacheKerberosServiceUser with the password aRandomPassword. Use your common sense and set a secure password when doing this in the real world.

When Apache needs to authenticate with Active Directory, it needs to use a Keytab file. A Keytab is a cryptographic file that can be used to represent a service (application) and it’s long-term “key” (also known as a password!) as it exists within Active Directory. This is particularly useful when your service (such as your website) is running on a non-Windows environment but still needs to leverage Kerberos.

To kick things off, Log in to your Domain Controller and open an elevated powershell prompt.

Creating the new User

I encourage you to follow your normal methods for creating a new Active Directory User but for efficiency here’s a quick powershell cmdlet that you can use.

New-ADUser `
    -Name "Kerberos User" `
    -GivenName "Kerberos" `
    -Surname "User" `
    -SamAccountName "ApacheKerberosServiceUser" `
    -AccountPassword (Read-Host -AsSecureString "Input User Password") `
    -ChangePasswordAtLogon $False `
    -Description "Service User for Apache Kerberos Authentication" `
    -DisplayName "Apache Kerberos Service User" `
    -Enabled $True

Creating a Keytab

Now that the AD User has been created, you’ll need to map a new Service Principal Name (SPN) to it and export a new Keytab. The SPN will be made of two parts. The first part will be “HTTP” to represent a web service, and the second part will be the ServerName definition from your Apache Virtual Host config file, separated with a forward-slash.

Assuming we are setting up Kerberos Auth for this website, the resulting SPN would be HTTP/ashdavies.online

Use the ktpass command to map the SPN to the AD User. In the below example I’m specifying an encryption type to use with the -crypto flag. AES256-SHA1 should be your preferred option here but if your environment prevents you from using it, the other alternatives are one of: AES256-SHA1, AES128-SHA1, RC4-HMAC-NT, DES-CBC-CRC or DES-CBC-MD5.

ktpass `
    -princ HTTP/ashdavies.online@ASHDAVIES.LAN `
    -mapuser ApacheKerberosServiceUser `
    -pass aRandomPassword `
    -crypto AES256-SHA1 `
    -ptype KRB5_NT_PRINCIPAL `
    -out C:\Temp\kerberos.keytab

If the above command runs without a hitch, you should be able to find the Keytab at the path specified – C:\Temp\kerberos.keytab.

We’re all done with Active Directory. Now you can move this Keytab file onto the Ubuntu Server for the next steps. You can transfer it over there however you like (FTP, PuTTY etc).

Once the Keytab is safely on your Ubuntu Server, you should move it to /etc/apache2/private/kerberos.keytab and change the ownership of the file to match the same user that Apache runs as. (Typically this is www-data)

sudo chown www-data /etc/apache2/private/kerberos.keytab

Preparing Apache

Out of the box, Apache doesn’t support authentication via Kerberos so you’ll need to install the module.

sudo apt install libapache2-mod-auth-kerb

Configuring your Virtual Host

Now that you’ve installed the module, you can configure your Apache Virtual Host file. In the below example we will edit the default Virtual Host that comes with Apache but you can substitute it for whichever one you wish to secure on your Ubuntu Server.

Edit /etc/apache2/sites-available/000-default.conf or any other vhost configuration file you want to use.

<VirtualHost *:80>
    # ...
    ServerName ashdavies.online    
  
    <Location />
        AuthType Kerberos
        AuthName "Kerberos authenticated website"
        KrbAuthRealms ASHDAVIES.LAN
        KrbServiceName HTTP/ashdavies.online
        Krb5Keytab /etc/apache2/private/kerberos.keytab
        KrbMethodNegotiate On
        KrbMethodK5Passwd On
        require valid-user
    </Location>
</VirtualHost>

You’ve just added a big block of code to the Virtual Host so let me break down what is going on in those few lines:

• AuthType is part of the default Auth tooling for Apache and simply informs it which authentication module should be loaded for this VirtualHost
• AuthName is presented to the User as a prompt when they first visit the website. This should be set to a friendly message to help the user understand what credentials they need to enter.
• KrbAuthRealms takes one or more arguments (separated by spaces), specifying the Kerberos realm(s) to be used for authentication. This defaults to the default realm taken from the local Kerberos configuration (/etc/krb5.conf)
• KrbServiceName should match the SPN that was assigned to the AD User and the corresponding key of this name must be stored in the Keytab.
• Krb5Keytab takes one argument, specifying the location of the Kerberos Keytab file. The keytab file must be readable for the apache process, and should be different from other keytabs in the system.
• KrbMethodNegotiate can be set to On or Off. To enable or disable the use of the Negotiate method. You need special support on the browser side to support this mechanism.
• KrbMethodK5Passwd can be set to On or Off. To enable or disable the use of password based authentication for Kerberos.
• and finally, require valid-user essentially states that only users that have been successfully authenticated may access this resource.

If you want to read more about the additional “Krb” prefixed module definitions you can read about Mod Auth Kerb on SourceForge.

Now that your Virtual Host configuration is done, finish off with:

sudo apachectl configtest

to check your VirtualHost for any potential errors. If the command returns Syntax OK then you can safely restart the Apache process with:

 sudo service apache2 restart

Wrapping up

Try accessing the website domain name. You should now be prompted with the message “Kerberos authenticated website” and asked for your username and password. Try logging in with a known AD User. If the connection to AD is successful and your user is authenticated you should now be granted access to the website!

Congratulations you’ve successfully configured Apache, Ubuntu, and Active Directory to support Kerberos Authentication on your website.

Stay tuned for a future article where I’ll be covering how to go one step further with this set up by adding support for Single Sign-On!