This tutorial contains my knowledge about using Apache/mod_auh_kerb and Windows 2000/2003/2008R2 as KDC.
Since Windows 2000 a Windows domain controller (DC) is able to act as Kerberos "Key Distribution Center" (KDC). This makes kerberized applications able to authenticate against a Windows domain via GSSAPI/Kerberos. Using mod_auth_kerb the Apache webserver is able to use Windows domains as user database and to do authentication not only via basicauth but also via WWW-Negitiate using GSSAPI/Kerberos. That means the browser does not send username/password to the webserver but a Kerberos ticket (wrapped into a GSSAPI-token) instead. See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsecure/html/http-sso-1.asp for a more technical description, RFC4559 "SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows" for the exact specification.
Benefits of GSSAPI/Kerberos authentication:
mod_auth_kerb Negotiate (GSSAPI Kerberos) | IIS Negotiate (GSSAPI SPNEGO Kerberos) | |
---|---|---|
Internet Explorer | since 5.5 on W2K/XP | since 5.5 on W2K/XP |
KDE Konqueror | since KDE 3.3.1 | since KDE 3.3.1 |
Mozilla Firefox | yes | yes |
Perl LWP with LWP::Authen::Negotiate | yes | yes |
Subversion | with neon 0.25.5 | ? |
Lynx | patch available (Karsten Künne) | |
Safari | Quoting Henry B. Hotz: Safari supports HTTP-Negotiate out of the box since mid-MacOS 10.4.x or so. It does not support delegation, period. |
Kerberos depends on a working and proper configured DNS because the application server's hostname is part of the Kerberos service-principal and the service-tickets.
This tutorial expects you to know
What's an A-record, a PTR-record, a CNAME record
How to use a DNS client like dig and how to do DNS-lookups and reverse-DNS-lookups
this tutorial expects you to know about basic Kerberos concepts. If you do not, I recommend reading first:
In detail I expect you to be familiar with:
("Key Distribution Center, a network service that supplies tickets and temporary session keys; or an instance of that service or the host on which it runs. The KDC services both initial ticket and ticket-granting ticket requests. The initial ticket portion is sometimes referred to as the Authentication Server (or service). The ticket-granting ticket portion is sometimes referred to as the ticket-granting server (or service)")
(a principal is someone or something you authenticate or authenticate to)
Kerberos representation of people sitting at a machine. Example: fredegar@GROLMSNET.DE)
on a kerberized host it holds the keys of service-principals
configuration of Kerberosinstallation, see man krb5.conf
maintains keytabfiles, see man ktutil
used to start authentication of a principal an to get a "Ticket granting Ticket" (TGT) man kinit
shows all tickets you got in your ticket cache since you run kinit.man klist
the elements of our example scenario:
is the Windows Domain and Kerberos-realm we want to use for authentication
ulmo.grolmsnet.de is the DNS-name of a Domain Controller (DC) of Windows Domain GROLMSNET.DE. It also acts as KDC of realm GROLMSNET.DE
beren.grolmsnet.de is the DNS-name of our Apache-machine we want to kerberize with mod_auth_kerb. Ensure you use the canonical hostname of beren.grolmsnet.de in ktpass command!
luthien.grolmsnet.de is the DNS-name of a W2K Workstation. luthien.grolmsnet.de is a member of Windows domain GROLMSNET.DE. We want the Internet Explorer to authenticate via Kerberos-ticket instead of username/password when accessing websites on beren.grolmsnet.de.
Please note that there is no direct communication between KDC ulmo and webserver beren when using SPNEGO!
Install Kerberos software on beren.grolmsnet.de, e.g. MIT Kerberos or Heimdal
configure beren to use Kerberos realm GROLMSNET.DE with KDC ulmo. Edit the /etc/krb5.conf file and put in a minimal configuration:
[libdefaults] default_realm = GROLMSNET.DE [domain_realm] beren.grolmsnet.de = GROLMSNET.DE [realms] GROLMSNET.DE = { admin_server = ulmo.grolmsnet.de kdc = ulmo.grolmsnet.de # # If using Heimdal and Windows2003 write # # kdc = tcp/ulmo.grolmsnet.de # # instead. }
See man krb5.conf for all details.
Make sure the etypes entries of [libdefaults] are empty! Heimdal users can use the KRB5_CONFIG environment variable to specify their own krb5.conf file if they are not able to edit the global /etc/krb5.conf file. The apachectl script is a good place for setting KRB5_CONFIG.
Read this section if you are not sure that kerberos works on machine beren.grolmsnet.de
Do a basic check of your Kerberos setup using kinit
achim@beren [~]$ kinit fredegar@GROLMSNET.DE
achim@beren [~]$ klist
create a dummyaccount in Windows Domain GROLMSNET.DE. It is used like a machine account. In this example the name of dummyaccount is kerbdummy1.
Ensure you use the canonical hostname of beren.grolmsnet.de in ktpass command. That means
if beren.grolmsnet.de is a CNAME-record use the DNS-name the CNAME record points to.
if beren.grolmsnet.de is an A-record ensure the corresponding PTR record points to beren.grolmsnet.de, too.
(In other words: reverse-DNS-lookup of beren.grolmsnet.de's IP address has to point to beren.grolmsnet.de
Use ktpass options as describe in the table below:
Windows 2008 R2 DC | Windows 2003 SP1 DC | Windows 2003 DC | Windows 2000 DC | ||
---|---|---|---|---|---|
encryption type | RC4 | AES256 (not supported by WinXP) | RC4 | DES (experts say DES is weak) | DES (experts say DES is weak) |
ktpass command | C:\>ktpass -princ HTTP/beren.grolmsnet.de@GROLMSNET.DE -mapuser kerbdummy1@GROLMSNET.DE -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -pass long!$longp2ass3word -out c:\temp\berenkeytab |
C:\>ktpass -princ HTTP/beren.grolmsnet.de@GROLMSNET.DE -mapuser kerbdummy1@GROLMSNET.DE -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass long!$longp2ass3word -out c:\temp\berenkeytab |
C:\>ktpass -princ HTTP/beren.grolmsnet.de@GROLMSNET.DE -mapuser kerbdummy1 -crypto rc4-hmac-nt -ptype KRB5_NT_SRV_HST -pass longlongpassword -out c:\temp\berenkeytab |
C:\>ktpass -princ HTTP/beren.grolmsnet.de@GROLMSNET.DE -mapuser kerbdummy1 -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass longlongpassword -out c:\temp\berenkeytab |
C:\>ktpass -princ HTTP/beren.grolmsnet.de@GROLMSNET.DE -mapuser kerbdummy1 -crypto DES-CBC-MD5 -pass longlongpassword -out c:\temp\berenkeytab |
ktpass description | http://technet.microsoft.com/en-us/library/cc753771(WS.10).aspx | http://technet2.microsoft.com/WindowsServer/en/library/5090598d-a735-4c73-9e37-1a95a4651fa51033.mspx | http://support.microsoft.com/default.aspx?scid=kb;en-us;324144 | ||
KDC's kvno ticket behavior | sends a ticket with a Key Version Number (KVNO). Ensure you have the correct kvno in your keytabfile, if the ticket has a kvno it must match! | sends no ticket with Key Version Number (KVNO) | |||
ktpass keytab behavior | kvno is properly exported to keytabfile | kvno is not properly exported to keytabfile, kvno-value in keytab is 1 for each run of ktpass. No problem when running ktpass one time, problem when ktpass is run more then one time because every run of ktpass increases the kvno in KDC. Workaround is to use -kvno=x option of ktpass with x = actual kvno + 1 |
The ktpass command creates the pricipal HTTP/beren.grolmsnet.de@GROLMSNET.DE, maps it to AD account kerbdummy1 and exports it's key to the keytabfile c:\temp\berenkeytab. Copy that file to beren.grolmsnet.de, you will need it in the next step.
Copy file
c:\temp\berenkeytab
from DC ulmoto the location where it sould reside on host beren - in our example
/usr/local/apache/conf/http_beren.krb5keytab
An alternate way to create the needed keytabfile is msktutil from Dan Perry. This tool you can use on your Unix box to create a keytab. With it there is no need to use ktpass nor copying keytabs around.
Check if the KDC sends correct tickets (kvno, enctype) by getting a serviceticket and using klist:
MIT Kerberos | Heimdal |
---|---|
achim@beren [~]$ kvno HTTP/beren.grolmsnet.de@GROLMSNET.DE achim@beren [~]$ klist -e |
achim@beren [~]$ kgetcred HTTP/beren.grolmsnet.de@GROLMSNET.DE achim@beren [~]$ klist -v |
check this values against keytab at /usr/local/apache/conf/http_beren.krb5keytab | |
MIT Kerberos | Heimdal |
achim@beren [~]$ klist -e -k -t http_beren.krb5keytab |
achim@beren [~]$ ktutil -k http_beren.krb5keytab list |
It's important to check in detail
1. | kvno | ticket's kvno must match kvno in keytab |
---|---|---|
2. | principal name | principal name in ticket must match the principal name in keytab |
3. | encryption type | If you have run the ktpass correctly the enctype
in ticket and keytab is - for example - DES-CBC-MD5.
If your
ticket's enctype differs from keytab's enctype (one is enctype RC4, the other DES, for example) mod_auth_kerb
will not work! |
If you want to kerberize additional hosts you need to create one dummyaccount an run ktpass per kerberized host.
Copy file c:\temp\berenkeytab from DC ulmo to the location where it sould reside on host beren (/usr/local/apache/conf/http_beren.krb5keytab in our example)
Make /usr/local/apache/conf/http_beren.krb5keytab readable (chmod 400) for the user that owns the httpd process.
Test if the created keytabfile works on maschine beren using kinit with loading key from keytabfile:
achim@beren [~]$ kinit -k -t /usr/local/apache/conf/http_beren.krb5keytab HTTP/beren.grolmsnet.de
to test your keytab, the HTTP entry in the Kerberos DB, and your Kerberos configuration on the web server. Make sure it's the right "kinit" if you have installed a separate Kerberos build for use by mod_auth_kerb.
If this doesn't work then you know it's your Kerberos config that's the problem and nothing to do with Apache or the module at all.
install Apache with DSO support and mod_auth_kerb as described in INSTALL
Platforms like Solaris or FreeBSD don't ship with GNU-make as default make.
Ensure that your buildprocess of mod_auth_kerb uses GNU-make, because the buildprocess works properly only when using GNU-make!
Because Windows does not support Kerberos4 I always use option --without-krb4 of mod_auth_kerb's ./configure script to get rid of all Kerberos4 warnings and errors in Apachelog.
edit the Apache httpd.conf file to make mod_auth_kerb use your Kerberos setup.
the following example makes an Alias topsecret to be accessable by GSSAPI-based authenticaion only.
Alias /topsecret/ "/home/achim/testwebroot/" <Directory "/home/achim/testwebroot/"> AuthType Kerberos KrbAuthRealms GROLMSNET.DE KrbServiceName HTTP Krb5Keytab /usr/local/apache/conf/http_beren.krb5keytab KrbMethodNegotiate on KrbMethodK5Passwd off require valid-user </Directory>
There is no need to use Directory directives, feel free to use Location or .htaccess files or whatever you like.
controls if your Apache uses Negotiate GSSAPI Keberos authentication. Set this to on, that's the SSO we want to use :-)
controls if your webserver uses BasicAuth with KDC as userdatabase. I always set this to off to get rid of annoying messages in Apache errorlog during debugging sessions. In a productive environment you can set it to on to allow non-kerberized webbrowser authenticate by BasicAuth (against KDC acting as userdatabase instead of passwd file)
See http://modauthkerb.sourceforge.net/configure.html for full description of mod_auth_kerb configuration.
Login to Workstation luthien using an account of domain GROLMSNET.DE
Turn on "Windows Integrated Authentification" in Internet Explorer. Make sure that webservers DNS domain (grolmsnet.de in our example) is listed in IE's local intranet site section as described in http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsecure/html/http-sso-1.asp
Use Internet Exploder to access http://beren.grolmsnet.de/topsecret/
Don't try to access the webserver via it's IP-address http://192.168.100.1 because
the FQDN used in URL http://beren.grolmsnet.de used in the browser must match the canonical hostname used in ktpass!
It should work now!
setspn -q principalnameto search for all accounts the principal is mapped
setspn -d principalname wrongaccountnameto remove the wrong mapping
Kerberos-Based SSO with Apache , another mod_auth_kerb HOWTO from Scott Lowe's Blog
msktutil from Dan Perry is a tool which you can use on your Unix box to create a keytab.With it there is no need to use ktpass nor copying keytabs around.
update of ktpass.exe http://support.microsoft.com/kb/919557 You receive pre-authentication errors when you use keytab files that are generated by using the Ktpass.exe tool on a Windows Server 2003 SP1-based computer
Many thanks to
Author: Achim Grolms. Feel free to send me corrections and feedback! modkerbtut@grolmsnet.de
last update 2011-02-07