Active Directory Kerberos authentication for Apache web server

UPDATED on 23 October 2018: There is a follow-up post for this article with some additional notes, which came as a result of an email conversation with one reader, who also struggled with the quirks of Kerberos+AD+Linux+Apache combination but managed to make it work after all.

I was recently involved in configuration of Kerberos authentication for a newly deployed Apache web site, using mod_auth_kerb module. We have an Active Directory environment with the largest part of our users working on Windows 7+ computers, but the Apache web site was supposed to be running on a Linux host. I configured an Apache web site hosted on a Linux box to use Kerberos to transparently authenticate AD users connecting from Windows computers (IE and Chrome browsers). I also enabled support for both RC4 and AES256 Kerberos encryption methods, and this was the trickiest part of all. While we still support the older RC4 encryption for Kerberos in our environment because we have some legacy systems not capable of using AES encryption, it is a very good idea to ensure that all new installations support AES by default as its more secure. You can find the following statement in the official IETF description of the Microsoft implementation of the RC4 encryption for Kerberos:
It is thus RECOMMENDED not to use the RC4 encryption types defined in this document if alternative stronger encryption types, such as aes256-cts-hmac-sha1-96 [RFC3962], are available.

Overview of configuration steps

There are many Internet resources describing the configuration process for Apache + mod_auth_kerb + AD - just google for “Apache mod_auth_kerb AD” and you get tons of step-by-step instructions and guides. But in the end, I had to gather pieces of information from many different source, because there was not one guide which explained all Kerberos machinery, options and required configuration actions in sufficient details in one place. The most useful and comprehensive resources that I was able to find are listed in the end of this document.

The tested configuration process looks like that:

1. Prepare and write down the crucial configuration parameters which you will use in the next steps:
   • Apache web site FQDN (more details on this below)
   • Active Directory account to be used as the service account (service identity) for this web site
   • FQDNs of at least two AD domain controllers that you are going to use as the KDCs for the Linux box
   • The DNS name of you AD domain
2. Prepare Linux box:
   • Install krb5-user package - binaries required to configure the Linux server as a “service” per Kerberos protocol terminology
   • Install Apache 2
   • Install mod_auth_kerb Apache module
3. Run Windows tool ktpass on AD domain controller to generate and output to the console two secret keys (for AES256 and RC4 encryption methods, respectively) associated with the service account specially created in the AD to be used as the identity of the web server. At this step I deviate from most of the instructions and manuals published in the Internet, because I discard the keytab file generated by ktpass and just take the values for the secret key and key serial number (vno) that I copy from the console output of this command and use them to create required entries in the keytab file manually on the Linux box. The reason why I make it so complicated is because I found no way to generate the keytab file directly using the ktpass tool for AES cipher as either the secret key was wrong because of the salt or the key was valid but the SPN was wrong.
4. Run Windows tool setspn on AD domain controller to configure proper SPN attribute (Kerberos Service Principal Name) in the properties of the service account AD object.
5. Create a DNS record for the public FQDN of the web server (the one entered in the browser address bar). If you have a single web site on your web server then the simplest option is to make sure that the public URL of your site is the same as the FQDN of the server configured in the /etc/hosts configuration file, and create an A DNS record for this FQDN pointing directly to the server’s IP address. However, if you want to host two or more web sites on the save web server with different host headers, then the situation becomes complicated and you will have to properly configure DNS CNAME records and keytab file. One option in this case is to use the same service account identity for all web sites hosted on the web server, configure keytab file for the server’s own FQDN configured in the /etc/hosts file and create CNAME DNS aliases for your web sited pointing to the server’s FQDN. The browsers will perform DNS name canonization and will request Kerberos service tickets not for the CNAME addresses of the web sites, but for the server’s own FQDN.
6. On the Linux box, use ktutil tool (part of the krb5-user package) to create a new empty keytab file and then use its addent subcommand to add two entries for AES256 and RC4 encryption schemes using the secret keys output to the console by ktpass tool at step 3.
7. Configure host-wide Kerberos parameters for the krb5-user package by editing configuration file /etc/krb5.conf
8. Configure mod_auth_kerb Apache module parameters by editing the Apache web site configuration file (i.e., /ect/apache2/sites-enabled/000-default.conf) and adding Kerberos specific entries under the VirtualHost section.
9. Optionally enable the fall-back mechanism available in the mod_auth_kerb which allows clients which do not support Kerberos to use Basic HTTP authentication scheme instead (SECURITY WARNING! Do not enable this option unless you also enable AND force SSL/TLS for your web site.)
10. Make sure that the browsers on Windows client computers are configured to start Kerberos authentication with your web site automatically and send the cached Windows credentials (check Internet Explorer “Local intranet” zone settings) ¹.

Example configuration step-by-step

The example below has been tested on a freshly installed Ubuntu system in a mixed Windows 2008R2/2012R2 AD domain controllers environments. Change the URLs, accounts and domain names to match your own settings and it should probably work for you as well.
As we remember, from the Kerberos protocol point of view, there are three computers participating in the authentication process: KDC (domain controller), service (Apache web server) and client (Windows computer accessing the web site). In the table below, the second column specifies the computer where the configuration commands and actions for the current step must be executed. The third columns specifies whether this step is a command that you need to execute or some other type of action that you must carry out. Run all commands exactly as given in the table in Windows CMD or Linux shell prompt. I executed all Linux commands with root privileges (sudo su), but you can prefix each command with sudo if you like. Many of the command parameters and settings in the configuration files are case sensitive, so it is very important to use exactly the same case for each step as is used in the example below!

Our example is for the following fictitious configuration:

• AD domain DNS name: company.com
• AD domain controller 1: dc1.company.com
• AD domain controller 2: dc2.company.com
• Web server FQDN: webserver1.company.com
• Web site URL: http://webserver1.company.com ²
• AD service account name (userPrincipalName): srvaccount1@company.com
• AD service account password³: THEpassword

krb5.conf

[libdefaults]
    default_realm = COMPANY.COM
    default_tkt_enctypes = aes256-cts-hmac-sha1-96 rc4-hmac
    default_tgs_enctypes = aes256-cts-hmac-sha1-96  rc4-hmac
    permitted_enctypes = aes256-cts-hmac-sha1-96 rc4-hmac


[realms]
    COMPANY.COM = {
            kdc = dc1.company.com
            kdc = dc2.company.com
            admin_server = dc1.company.com
    }

[domain_realm]
    .company.com = COMPANY.COM
    company.com = COMPANY.COM

<Location>

<Location />
  AuthType Kerberos
  AuthName "Active Directory"
  KrbAuthRealms COMPANY.COM
  KrbServiceName HTTP
  Krb5Keytab /etc/apache2/kerb.keytab
  KrbMethodNegotiate On
  KrbMethodK5Passwd Off
  require valid-user
</Location>

Testing the results

If you correctly configured all components, you should be able to launch Internet Explorer, Edge or Chrome browser on a domain joined Windows machine and open http://webserver1.company.com without any password prompt. You can also verify if a Kerberos ticket was issued by the KDC (domain controller) to your client system to be used for authentication against the web server. Type the following command in the CMD prompt:

klist

You should get the list of Kerberos tickets for various services that your system is talking to ¹. Find the ticket for http://webserver1.company.com and check the KerbTicket Encryption Type and Session Key Type fields. These two fields specify the encryption method that the KDC used for encrypting the issued service ticket and the requested encryption method that will be used for the session key between the client and the server, respectively ⁵.

Background information

How Kerberos authentication works

First of all, you have to define how your web site will be accessed by the clients from the DNS and IP address assignment point of view. There can be many possible configurations, and we have to know exactly how DNS records are configured and how IP connections from the clients to the web server are routed. The main thing to remember is that Kerberos clients (web browsers on Windows clients) use DNS lookups and special Kerberos protocol functionality to find out which AD account is the identity of the web server they are connecting to. In other words, they need to know the service account name for the web server in order to generate a valid Kerberos service ticket which can only be used by this particular account. The whole process looks like that:

• A user launches IE or Chrome browser on his Windows PC joined to the AD domain while being connected to the corporate network;
• He enters http://webserver.company.com in the browser address bar and presses Enter;
• The browser issues a DNS lookup for the hostname webserver.company.com;
• If the DNS server returns an A record with the IP address for webserver.company.com, it is considered to be the canonical DNS name of the web server. However if DNS replies with a CNAME (DNS alias) record for webserver.company.com and then resolves the alias to an A record with a different hostname anotherhost.company.com, then this second hostname will be considered to be the canonical DNS name of the web server, and all SPN lookups will be issued for that anotherhost.company.com FQDN and NOT for the original FQDN webserver.company.com entered in the address bar! This issue with CNAME aliases is often a major source of confusion, so it might be a good idea to look through a couple resources here and here to get the idea of the whole process. The popular approach is to only create A type DNS records for your web sites with Kerberos authentication, so that the FQDN in the address bar is directly resolved to the actual IP address of the web server or to the VIP of the load balancer if one is used.
• The browser constructs the so called SPN (Service Principal Name) the canonical DNS name it determined in the previous step. The SPNs a strings used to server as identifiers of resources and services in the network and are actually just string values in the format like that:
  • HTTP/webserver.company.com (this form of SPN identifier is commonly used for web servers)
  • HOST/server1.company.com (SPN for some generic service running on computer server1.company.com)
  • MSSQLSvc/sqlserver.company.com:1433 (SPN for MS SQL Server instance running on machine sqlserver.company.com on TCP port 1433)
• The browser issues a special Kerberos request (KRB_TGS_REQ) to its KDC specifying the SPN string as a parameter. The KDC looks through its accounts database searching for an account associated with the requested SPN. In our case KDC is an AD domain controller and it searches for a user/computer account having an LDAP attribute named servicePrincipalName with the value equal to the SPN string in the request. In corporate AD environment, the common practice is to create a separate “service” account for each distinct service/URL/web site, which is technically a regular AD user account often configured with a more relaxed password expiration policy.
• The KDC should find one and only one matching account for each SPN. In this ideal case it generates a so called Kerberos service ticket and returns it to the calling browser application in KRB_TGS_REP response. If KDC finds more than one matching account for one given SPN, it is a considered an error state and Kerberos authentication in this case won’t work. The same goes for the case if KDC cannot find any matching account at all.
• The Kerberos service ticket generated by the KDC contains in its encrypted payload some key data which can only be decrypted using the password for the account associated with the SPN. This ticket cannot be used with any other account!
• The browser sends the service ticket to the web server.
• The web process on the web server tries to decrypt the ticket it received from the browser. If we are taking about Apache running on Linux with mod_auth_kerb, it looks for a special keytab file which must be supplied by the administrator. This keytab file is essentially a small database, matching SPN strings to secret keys to be used for encryption/decryption. Its structure is like that:

• As you can see, the keytab file in our example contains two entries for the same SPN, but for two different ciphers - AES256 and RC4. And, of course, we have a separate keys of different length for each cipher. Not incidentally, our real keytab file that we are going to create will look just like that and will have two keys for two algorithms for the same one SPN of our web server. We configure it this way because in many networks both ciphers (RC4 and AES) are used simultaneously. In my organization, my own computer sometimes gets RC4 service tickets from the KDC even while the AES cipher is the preferred algorithm for recent Windows versions ⁵. Is these conditions some clients may obtain RC4 service tickets for authentication to our web server, while others may get and send to the web server AES encrypted tickets, and our web server must be able to decrypt both types.
• If the web server is able to find the matching entry in the keytab file ², it extracts from it the secret key and uses it to decrypt and verify the service ticket received from the browser. If the decryption and verification is successful then the client is deemed to be authenticated.

Different scenarios for DNS configuration and hosting multiple sites on one web server

In the table below, I outlined two possible scenarios and my recommendations for DNS and keytab configuration.

References

1. Mod_auth_kerb official page
2. The RC4-HMAC Kerberos Encryption Types Used by Microsoft Windows
3. How-to – Single sign on with Active directory and Apache
4. How the Kerberos Version 5 Authentication Protocol Works
5. Kerberos Keytabs – Explained
6. All you need to know about Keytab files
7. Encryption Type Selection in Kerberos Exchanges
8. ktutil - problems generating AES keys (salt?)
9. Apache sends wrong server principal name to Kerberos
10. Kerberos configuration known issues
11. The Chromium Projects - HTTP authentication
12. Why you can still have duplicate SPNs in AD 2012 R2 and AD 2016

Notes