Single Sign On With Active Directory and PHP on Ubuntu

I've been working on some linux hosted sites within windows domains recently and found it difficult to find a solid guide to single sign on with Active Directory and Ubuntu. I've got to be honest in hind sight it it all seems quite simple but its a different story a 4:30 on a friday afternoon so with that in mind maybe this guide will be of use.

The authentication process relies on several technologies to operate:

Example Domain: ncl.johnthedeveloper.co.uk
Web Server: alpha.ncl.johnthedeveloper.co.uk
Active Directory Server: beta.ncl.johnthedeveloper.co.uk
DNS Server: beta.ncl.johnthedeveloper.co.uk

In this setup we are using a single web server supported by an AD domain controller, which also provides DNS and Kerberos KDC services using Windows Server 2003 SP2, however the same process should also apply to later distributions.

We are assuming that the web server is set up and running, providing content to its FQDN over HTTP. In our examples this server is an Ubuntu 12.04LTS LAMP server. In addition to HTTP services we are also assuming that the AD server is correctly set up and providing authentication services to users of the domain.

NOTE: KDC services (used in the authentication process) are provided by AD by default, supported by the records created automatically in the DNS zone when using an active directory integrated zone. If you're not using an AD integrated zone you will need to set up the required KDC DNS records manually.

NOTE: For services to operate each host must have a valid FQDN & DNS entry within the domain and a valid PTR record for reverse lookups. To avoid issues with key generation avoid the use of CNAME records when creating the hosts involved.

Now to business...

1. Install and configure Kerberos

The Kerberos installation guide for Ubuntu Server can be found at:

https://help.ubuntu.com/community/Kerberos

Once Kerberos is installed we need to modify the configuration to include the settings outlined below.  In our example the distributions config file can be found at /etc/krb5.conf.

[libdefaults]
        default_realm = NCL.JOHNTHEDEVELOPER.CO.UK

[realms]
        NCL.JOHNTHEDEVELOPER.CO.UK = {
                kdc = beta.ncl.johnthedeveloper.co.uk
                admin_server = beta.ncl.johnthedeveloper.co.uk
        }

[domain_realm]
        .ncl.johnthedeveloper.co.uk = NCL.JOHNTHEDEVELOPER.CO.UK
        ncl.johnthedeveloper.co.uk = NCL.JOHNTHEDEVELOPER.CO.UK

NOTE: uppercase must be used when referring to the root domain. DNS entries for individual hosts do not require this.

2. NTP synchronization

In order for Kerberos tickets to operate correctly the system time on each host must be within allowed tolerances. To achieve this our web server must update its system time to match the AD server. This can be done by adding the line below to the NTP config file, which in our distribution can be found at /etc/ntp.conf.

server beta.ncl.johnthedeveloper.co.uk

In addition to this we add a daily update to the crontab making sure the synchronization takes place on a regular basis. This can be achieved by creating the file /etc/cron.daily/ntpdate containing the following line.

ntpdate beta.ncl.johnthedeveloper.co.uk

3. Web server authentication user and keytab generation

In order for the web server to authenticate user accounts it must itself have an associated active directory user account. In this example we have named the user “Kerberos”.  The Kerberos user must be manually associated with a keytab file that will allow the web server to authenticate requests in the background.  To create the keytab enter the following statement in a command prompt.

ktpass -princ HTTP/alpha.ncl.johnthedeveloper.co.uk@NCL.JOHNTHEDEVELOPER.CO.UK -mapuser kerberos@NCL.JOHNTHEDEVELOPER.CO.UK -pass password -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -out C:\Temp\kerberos.keytab

NOTE: Windows Server 2003 does not install ktpass by default. The application is available in the support tools package on the Server 2003 install media.

Once the keytab file has been generated it must be transferred to the web server and given the correct ownership and permissions. In our example we are storing the keytab file at /etc/kerberos.keytab. To set the correct ownership and permissions use the commands below.

chown root:www-data /etc/kerberos.keytab
chmod 0640 /etc/kerberos.keytab

NOTE: The Linux distribution in our example runs apache processes under the www-data user. In other distributions this may differ.

4. Install apache 2 mod auth kerb

To install the apache module required for the web server to communicate with Kerberos run the following:

apt-get install libapache2-mod-auth-kerb

NOTE: The Linux distribution in our example enables the module automatically. In other distributions some extra configuration may be required. Documentation for the module can be found at http://modauthkerb.sourceforge.net

5. Configure the web server to require authentication

The final step in the setup process is to tell the web server that authenticated users are required and to define the authentication method. This can be done by adding the following code to the virtual host block in apache config.

AuthType Kerberos
AuthName "NCL Intranet"
KrbAuthRealms NCL.JOHNTHEDEVELOPER.CO.UK
KrbServiceName HTTP
Krb5Keytab /etc/kerberos.keytab
KrbMethodNegotiate On
KrbMethodK5Passwd On
require valid-user

Restart apache and Bob's your tea pot. The web server should now be authenticating users based on their active directory credentials.

Further Information

Internet Explorer will automatically use the active directory session of the current user for websites that it deems to be local intranet sites. When this is not the case the AD integration will still operate however the user will be prompted to enter their account details before content is made available.

To force IE to treat the website as a local intranet site the URL must be added to the sites list in Internet Options > Security > Local intranet > Sites > Advanced. This action can be performed on bulk using an active directory group policy however this is outside of the scope of this guide.