NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Windows 2003 Authentication using Kerberos and mod-auth-kerb

This is a discussion of the TWiki I setup on linux that transparently authenticates Windows users. There were a few snags that required sifting through many websites. This is my effort to improve that experience for others.

Our Information

For this explanation I'll use sample data - replace with your own.

• Active Directory/DNS domain: acme.local
• Windows 2003 Server: win2k3.acme.local
• Linux/TWiki Server: wikisvr.acme.local
• Username in AD: wikikerb

Setup TWiki

I am running Ubuntu so I installed TWiki and Apache using the steps in TWikiOnUbuntu.

Setup Kerberos

Install MIT Kerberos. On Ubuntu the package manager can install this:

sudo apt-get install krb5-user

The dependencies for this package will provide the rest of the required files.

Edit /etc/krb5.conf

[libdefaults]
    default_realm = ACME.LOCAL

[domain_realm]
    acme.local = ACME.LOCAL
[realms]
     ACME.LOCAL = {
                      kdc = win2k3.acme.local
                      admin_server = win2k3.acme.local

Test your Kerberos configuration so far:

• Ensure that you can ping between the Windows 2003 server and the linux server in both directions and using both the fully-qualified domain name (win2k3.acme.local) and the IP address.

Note: You must be able to ping your Windows 2003 KDC using the fully-qualified domain name from the linux host. In the unlikely event you have mDNS enabled this will fail if your Active Directory domain ends in .local. If you try to work around the name resolution issue by entering the IP address in krb5.conf, the next test will succeed but Apache authentication will fail later with "No principal in keytab matches desired name" in the Apache error log.

• In a shell type kinit username@ACME.LOCAL, entering an Active Directory username you know. If it is successful it will ask for the account's password and then exit without an error. Use klist to view the Kerberos ticket that was just added to the machine.

Setting up a keytab file

Now switch to your Windows 2003 server and create a user account that will represent the HTTP service on the linux server. Let's use wikikerb. We will use ktpass from the Windows 2003 Support Kit to create a keytab file the linux server will need. At the command line, enter

ktpass -princ HTTP/wikisvr.acme.local@ACME.LOCAL -mapuser wikikerb -mapop set +desonly -pass accountpassword -out c:\http.keytab

Note: Even if you created a CNAME to redirect wiki.acme.com to wikisvr.acme.local, and all your users will be entering wiki.acme.com, the principal name (-princ) must still use the canonical DNS name. This will not affect what your users need to type to get to the site.

Copy the keytab file to the linux server and place it in /etc/apache2.

Test the keytab file like so:

kinit -k -t /etc/apache2/http.keytab HTTP/wikisvr.acme.local

This should exit without any error messages, and this Kerberos ticket will now appear in klist. If you want to purge the ticket cache use kdestroy.

For more information see the guide at http://grolmsnet.de/kerbtut/

Setup mod-auth-kerb

Once again the package manager works wonders:

sudo apt-get install libapache2-mod-auth-kerb

In /etc/apache2/conf.d/twiki.conf, add the entries for Kerberos authentication. Enter # in front of AuthType basic to disable plain text authentication.

<Directory /usr/lib/cgi-bin/twiki/>
   Order Deny, Allow
   Allow from all
   
   AuthType Kerberos
   KrbAuthRealms ACME.LOCAL
   KrbServiceName HTTP
   Krb5Keytab /etc/apache2/http.keytab
   KrbMethodNegotiate on
   KrbMethodK5Passwd on
   Require valid-user
</Directory>

Setup Plugins

Kerberos authentication will set the login name TWiki sees to username@ACME.LOCAL. To map these login names to WikiNames, I use LoginNameAliasesPlugin and LdapContrib.

LoginNameAliasesPlugin

Be sure to download the new version of LoginNameAliasesPlugin that is compatible with 4.1 from LoginNameAliasesPluginDev and not the older version on the main page. Once installed setup suffix removal of ACME.LOCAL.

-- Contributor: MattEverson - 05 Dec 2007

Comments & Questions about this Supplemental Document Topic

Thanks Matt for contributing this topic. I moved it from the Main web, linked to it from TWikiUserAuthenticationSupplement and tagged it so people can discover it.

-- PeterThoeny - 07 Dec 2007

Excellent! I am using a similar setup, but have to apologize that I was too lazy to write it down. I am curious about how you are using LdapContrib to create wikinames. Do you require your users to register or do you pull their data from LDAP on-the-fly?

-- HaraldJoerg - 08 Dec 2007

For anyone who is trying this on Windows Server 2008, there is a bug in Active Directory that authentication with principals that contain a slash (such as HTTP/wikisvr.acme.local) in the name is broken. It took me a day to find this out, and I hope this can save others some hair-pulling time.

-- BeilinZhang - 06 May 2008