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.
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 VirtualHostAuthName
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 toOn
orOff
. 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 toOn
orOff
. 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!