Kerberos/Kerberos and Debian

From Authentication Tools for Joomla! (JAuthTools)

(Difference between revisions)
Jump to: navigation, search
(Linux box setup)
(Windows configuration)
Line 97: Line 97:
The Support Tools also include the "ADSI Edit" MSC which is the swiss army knife of manipulating Active Directory's back end.
The Support Tools also include the "ADSI Edit" MSC which is the swiss army knife of manipulating Active Directory's back end.
 +
 +
'''Note:''' ktpass.exe is a command line utility, you will need to start a command prompt first. kerbtray.exe is a tray icon based application (hides in the tray on launch) and ldp.exe has a full GUI.
=== Creating the accounts ===
=== Creating the accounts ===
Line 113: Line 115:
=== Creating the keytabs ===
=== Creating the keytabs ===
-
The next step is to create the keytab for both of the users. This is another find and replace operation, the command in question is:
+
The next step is to create the keytab for both of the users. You will need to create a new command prompt window first, I suggest that using the one under the "Support Tools" menu item is the best way of achieving this goal. This is another find and replace operation, the command in question is:
  ktpass -princ <b>SERVICE</b>/<b>FQDN</b>@<b>REALM</b> -mapuser <b>DOMAIN\account</b> -crypto DES-CBC-MD5 +DesOnly -pass <b>password</b> -ptype KRB5_NT_PRINCIPAL -out <b>filename</b>
  ktpass -princ <b>SERVICE</b>/<b>FQDN</b>@<b>REALM</b> -mapuser <b>DOMAIN\account</b> -crypto DES-CBC-MD5 +DesOnly -pass <b>password</b> -ptype KRB5_NT_PRINCIPAL -out <b>filename</b>

Revision as of 05:47, 23 February 2009

This guide covers Windows Server 2003 and Debian 4.0 configuration. Please note that there are noted issues with 2003 SP1, I suggest upgrading to SP2/R2 where possible to resolve these issues before you start. Alternateively look at the Kerberos page and view the links mentioning 2003 SP1 issues. If you want to continue with 2003 SP1, consult Microsoft KB 919557. If you have issues you may wish to look at the Kerberos Troubleshooting page to see if your specific error is listed. Active Directory has a habbit of being case sensitive for some interfaces (typically non-MS ones) and being very forgiving of case in others (typically MS tools). Case is always important, so make sure that this is typed appropriately.

Contents

Before we begin

Terminology

The following terms are more or less equivalent and may be used interchangeably. Some may also suggest replacements, for reference they are all listed here:

Kerberos realm Active Directory Domain, Active Directory Site; typically this means writing the site name in capitals, see below
REALM Your AD realm, typically your DNS site name all in capitals; in this case its SITE3.DIGITALPAPER.HOMELINUX.NET
SERVERNAME Substitute this with the name of your Linux server
FQDN The fully qualified domain name; you may need to fill this in for specific commands

Where possible, items requiring replacement are marked in bold.

AD Domain Setup

The set up in this case is actually mildly unique. There are two servers, one called "pie" (Debian 4.0) and another called "notpie" (Windows 2003). "notpie" has the AD site "site3.digitalpaper.homelinux.net" assigned to it and its DNS also contains entries for the digitalpaper.homelinux.net domain as well. "pie" is not a member of the domain and not actually in the same subdomain. For reference:

Server Name FQDN IP address
notpie notpie.site3.digitalpaper.homelinux.net 192.168.1.20
pie pie.digitalpaper.homelinux.net 192.168.1.10

We want to authenticate requests to Apache on pie from clients in the Kerberos realm SITE3.DIGITALPAPER.HOMELINUX.NET (the site name all in caps) in a way that doesn't require a password or uses their domain logins. A noble goal, and for bonus mark we're mixing our domains around a bit. The down level (pre 2000) name for the domain is "SITE3".

From this point, I'm going to assume that the above is setup already and working properly.

Linux box setup

I'm assumimg you have a working Debian 4.0 machine with Apache 2 up and running. Some of the instructions use Apache 2, if you are using Apache 1 you will likely need to modify them slightly (possibly removing the "2"). The machine should have some form of an IP address and DNS hostname assigned to it within the Active Directory Domain Controller's DNS server or in a DNS server that both machines can acknowledge. For the purposes of this tutorial we are going to assume that your domain controller is your DNS server and that your Linux server exists in its DNS properly. We only have two machines, the Linux box and the domain controller so if your set up is different, some of the values used may not meet this assumption. You will have to change this where necessary. I would also advise installing and configuring NTP to point to your domain controller to ensure that your time is synchronised otherwise clock skew errors may appear.

No matter where your DNS is located you will need to ensure that forward and reverse lookups for the Linux box are properly working so that you can resolve it appropriately.

I'm also going to presume that you have Joomla! 1.5 set up and installed with the LDAP plugins configured properly and working. Ideally if you have a base set up with Joomla! site already authenticating to Active Directory this would be a useful point to launch from. Since we're trying to get SSO working, the Joomla! 1.5 site obviously needs to be on the same server.

System Configuration

Linux Configuration

Our first port of call is to set up the Linux server to look towards the AD domain. You may have done this already, but you may not have. Most of the files referenced exist as full copies at the end of this page for reference.

Installing software

Before we begin, we're going to need some tools installed:

sudo aptitude install krb5-user libapache2-mod-auth-kerb

Please note that this will also install krb5-config which will request information such as your KDC and similar servers as well as the realm. Depending on your debconf configuration, it may automatically detect the realm from the FQDN of the machine. If this assumption is wrong (as it was for mine) then you will have need to reconfigure the package to work properly and enter the appropriate default realm:

sudo dpkg-reconfigure krb5-config

And fill in the values properly.

If you have already got krb5-config installed it may be worthwhile reconfiguring it anyway to validate that the settings it has are correct. If it is wrong it will cause you issues further along.


/etc/resolv.conf

Since we've got two domains we care about (one that "pie" is in and the one for the AD domain and "notpie"). This will configure the Linux machine to search both domains and use AD as the domain controller.

search site3.digitalpaper.homelinux.net digitalpaper.homelinux.net
nameserver 192.168.1.20

/etc/hosts

One of the useful tidbits I've picked up is ensuring that your local hosts file is set up with the correct external IP address for the DNS domain name and not pointing back to everyone's favourite IP address 127.0.0.1:

192.168.1.10 pie.digitalpaper.homelinux.net pie

The order is also important, make sure that the FQDN is before the shorter name. Using the external interface address instead of local loopback is also important and will help us to avoid other issues later on with Kerberos.

/etc/krb5.conf

This is the main Kerberos configuration file, Debian will automatically generate this file for you when you installed the krb5-config package. With any luck, it should look like the sample at the end of this document with your values instead of mine and probably a bit more junk. In my due domain situation, I needed to do one more modification in the [domain_realm] section of the document to add the domain for pie. This enables the server to find the correct realm for itself. There should be some lines already but the looks like this when completed fully:

[domain_realm]
        .site3.digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
        site3.digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
        .digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
        digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET

At this point we should to be authenticate as a Kerberos user and obtain a Kerberos ticket, so lets authenticate as a user with kinit to check if things work:

kinit username
Password for username@REALM: (type users password here)

With any luck this will complete without error. If you do encounter an error, check out the Kerberos troubleshooting page to see how you can resolve the issue. You may also optionally specify a realm instead of just the username but the command should default to the correct realm anyway.

Samba Note

If you're using Samba, you may wish to check out a comment on Scott Lowe's guide on Kerberos SSO with Apache from Emmanuel Gomez. In theory, this should absolve you from having to do any configuration on the Windows side and your keytab for both the operating system and Apache would be one file. I haven't tried this option, and prefer the method detailed below.


Windows configuration

Presuming that this is all done we now need to configure AD with accounts for the Linux box and Apache.

Installing software

You will need the Windows 2003 Support Tools otherwise your install won't have ktpass.exe and other useful utilities (ldp.exe and kerbtray.exe are two hidden jewels of the system). You will need this to be installed before you can continue. I would advise that you at least login and log off (or if possible restart) after installing these tools to get the path available otherwise you will need to type commands like the following to get to the tools:

"C:\Program Files\Support Tools\ktpass.exe"

If you have issues where you get the error "command not recognized" or similar, you may need to use the full path to the tool. Restarting the server or cycling your login should resolve these issues.

The Support Tools also include the "ADSI Edit" MSC which is the swiss army knife of manipulating Active Directory's back end.

Note: ktpass.exe is a command line utility, you will need to start a command prompt first. kerbtray.exe is a tray icon based application (hides in the tray on launch) and ldp.exe has a full GUI.

Creating the accounts

In my sample tree, I have a "Servers" OU that I use to store accounts for servers or service accounts in one location. If you haven't got one already (or something similar), I suggest that now is the time to create one.

Please note here that it appears important that in the following section these are users and not computers, and there is one user per service (including one for the host). The logic for this appears to be that when using a single 'computer' account that the key version number increases automatically invalidating previously generated keys. There is a work around that I haven't tested available as a comment on Scott Lowe's blog. For those of us less daring, we'll go for the simpler option.

Within that OU we're going to create two new "users". The first will be for the host itself and the second will be for Apache. In the new user screen set the:

  • first name to be "host"
  • last name to be SERVERNAME, in our case "pie".
  • logon to be "host-SERVERNAME", so "host-pie"
  • click next and then tick the "password never expires" box and finish

Repeat this with a second user, replacing instances of "host" with "HTTP". Please note that case is sensitive so ensure host is all lower case and HTTP is all upper case. Please note the password that you gave the users as you will use this again when creating the Kerberos keys.

Creating the keytabs

The next step is to create the keytab for both of the users. You will need to create a new command prompt window first, I suggest that using the one under the "Support Tools" menu item is the best way of achieving this goal. This is another find and replace operation, the command in question is:

ktpass -princ SERVICE/FQDN@REALM -mapuser DOMAIN\account -crypto DES-CBC-MD5 +DesOnly -pass password -ptype KRB5_NT_PRINCIPAL -out filename

So we need to replace SERVICE, FQDN, REALM, the username you set the account to be, the password and give the tool a unique filename where it can output the file. Keep in mind that the downlevel version of our site is "SITE3" and that the service is either "host" or "HTTP". You may have other services depending on your setup but this isn't covered here.

For simplicity I recommend creating a folder on your desktop or in your My Documents folder and navigating to this folder in the terminal and then running the following commands. It places your keytabs in one central location which makes finding them later and updating them if need be easy. I created a "keytabs" folder on the desktop to store the files in.

The sample commands I used were the following:

ktpass -princ host/pie.digitalpaper.homelinux.net@SITE3.DIGITALPAPER.HOMELINUX.NET -mapuser SITE3\HOST-pie -crypto DES-CBC-MD5 +DesOnly -pass password -ptype KRB5_NT_PRINCIPAL -out host-pie.keytab
ktpass -princ HTTP/pie.digitalpaper.homelinux.net@SITE3.DIGITALPAPER.HOMELINUX.NET -mapuser SITE3\HTTP-pie -crypto DES-CBC-MD5 +DesOnly -pass password -ptype KRB5_NT_PRINCIPAL -out http-pie.keytab

This will output a lot of data to the screen but should ultimately result in success presuming that you've fed the accoun the right information. If you do encouter errors check over the command to ensure that you haven't missed something out.

Once we've created the keytabs we need to shift them to the Linux server. The file "host-pie.keytab" will become /etc/krb5.keytab and the file "http-pie.keytab" should be copied to a new folder, "/etc/apache2/keytab" so that we can use it later. This should be done in a secure manner, so I suggest using SCP or similar to transfer the files.

Testing the keys

Once the keys have been transferred to their relevant location on the Linux server, we can test them to see if they are working properly with 'kinit' again on the Linux server. This time the command looks a little different:

kinit -k SERVICE/FQDN

This will work for 'host' but will probably fail for the 'HTTP' service, for that we will need to specify a location for the keytab. The commands I used in this case were as follows:

kinit -k host/pie.digitalpaper.homelinux.net
kinit -k -t /etc/apache2/keytab/http-SERVERNAME.keytab HTTP/pie.digitalpaper.homelinux.net

Note: This assumes that you've copied the files to correct location already. If you have transferred the HTTP key to a different location you may wish to specify a different option for -t. If everything is working properly you should not receive any error from these commands and running 'klist' after each one should show that you have a ticket for either account. If you do have an error check out the Kerberos troubleshooting page for guidance.

mod_auth_kerb Configuration

The last part of this saga is configuring mod_auth_kerb to work properly in your environment. Presuming you have it installed properly, this is usually straight forward as during installation the module is normally automatically enabled. Resolving the errors resulting from configuration can sometimes be a tad more problematic. If you do have an error check out the Kerberos troubleshooting page for guidance and make sure to check the Apache error log. You may also wish to increase the logging and debugging level of Apache to obtain more information about what is actually happening behind the scenes with Kerberos.

Using a .htaccess file

Presuming that the location you want to protect is configured to accept .htaccess files, you can use the following to protect the folder. You will probably need in a directory directive in your main Apache configuration file with either a "AllowOverride All" or "AllowOverride AuthConfig" directive.

 AuthType Kerberos
 AuthName "Kerberos Login"
 KrbMethodNegotiate On
 KrbMethodK5Passwd On
 KrbAuthRealms REALM
 Krb5KeyTab /etc/apache2/keytab/http-SERVERNAME.keytab
 require valid-user

Within the Apache configuration

If you wrap the same command used in your .htaccess file within either a Location directive or a Directory directive and then restart Apache this location should be protected by Kerberos

Set up a test page

You may wish to set up a test page in your location. As you are likely to have PHP available, I suggest creating a simple file called 'test.php' and putting in the file:

<?php phpinfo(); ?>

This should give you a diagnostic of PHP, which include the server authentication variables that are passed to it. This way we will be able to see if the user is in fact authenticated and who Apache has authenticated them as and which method it used to do so.

Browser Configuration

With any luck your changes are successful and now its time to test it. Navigate to the directory you decided to protect (in my case I decided to use /kerberos) and you should be either let directly through or prompted for a username and password. Either way you should end up being authenticated and if you created the test.php file you could validate the method. If you were let directly through you should have the Auth Type "Negotiate" however if you needed to type in a password your auth type would be "Basic" (this is "AUTH_TYPE" in the PHP info page if you are looking for it). Just above that field should be "REMOTE_USER" which should be set to your AD UPN, e.g. username@REALM. See the browser support page for information in relation to browser support issues (not configuration).

Some browsers (e.g. Safari on Mac; IE on Windows) will automatically work if the underlying layer is configured properly.

IE Configuration

There are two issues that may occur with IE. The first is that Integrated Windows Authentication is not enabled (the default for IE6) and the second is that it may think that the site isn't on the intranet.

  • The first is easy to solve, to enable the browser to respond to a negotiate challenge and perform Kerberos authentication, select the Enable Integrated Windows Authentication check box in the Security section of the Advanced tab of the Internet Options menu, and then restart the browser.
  • The second requires a tad more effort, check on the bottom right hand corner what zone the site is in. If it is in the "Internet" zone then you will likely have issues. Double click on this and click on Local Intranet -> Sites -> Advanced -> Add. Then click close or ok on all dialogues until you return to your browser. It should now identify the site as being in the local intranet. For alternate ways of solving this problem look at Microsoft KB article 303650 about "IE not correctly identifying sites in the intranet".

If after this has all been done the user is still being prompted for a password, check the Apache logs for any errors that might have occured. Keep in mind that the desktop needs to be joined to the domain for IE to function correctly with SSO.

Firefox configuration

Assuming that you have Kerberos set up on your client (e.g. Windows machine joined to the domain, Linux or Mac OS X box set up to obtain a Kerberos ticket) all you should need to do is set "network.negotiate-auth.trusted-uris" to the name of your web server. With this it should work.

Safari

Safari has no configuration option and if its working at the lower levels, 'just works' and if not then you've got to dig through the lower levels to work out what is wrong. This applies to both Windows and Mac versions.

Sample Files

Apache Configuration

<Location /kerberos>
  AuthType Kerberos
  AuthName "Kerberos Login"
  KrbMethodNegotiate On
  KrbMethodK5Passwd On
  KrbAuthRealms SITE3.DIGITALPAPER.HOMELINUX.NET
  Krb5KeyTab /etc/apache2/keytab/http-pie.keytab
  require valid-user
</Location>

.htaccess File

  AuthType Kerberos
  AuthName "Kerberos Login"
  KrbMethodNegotiate On
  KrbMethodK5Passwd On
  KrbAuthRealms SITE3.DIGITALPAPER.HOMELINUX.NET
  Krb5KeyTab /etc/apache2/keytab/http-pie.keytab
  require valid-user

resolv.conf

search digitalpaper.homelinux.net site3.digitalpaper.homelinux.net
nameserver 192.168.1.20

krb5.conf

[libdefaults]
        default_realm = SITE3.DIGITALPAPER.HOMELINUX.NET

# The following krb5.conf variables are only for MIT Kerberos.
        krb4_config = /etc/krb.conf
        krb4_realms = /etc/krb.realms
        kdc_timesync = 1
        ccache_type = 4
        forwardable = true
        proxiable = true

# The following libdefaults parameters are only for Heimdal Kerberos.
        v4_instance_resolve = false
        v4_name_convert = {
                host = {
                        rcmd = host
                        ftp = ftp
                }
                plain = {
                        something = something-else
                }
        }
        fcc-mit-ticketflags = true

[realms]
        SITE3.DIGITALPAPER.HOMELINUX.NET = {
                kdc = 192.168.1.20
                admin_server = 192.168.1.20
        }

[domain_realm]
        .site3.digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
        site3.digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
        .digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
        digitalpaper.homelinux.net = SITE3.DIGITALPAPER.HOMELINUX.NET
[login]
        krb4_convert = true
        krb4_get_tickets = false
Personal tools