Thank to http://www.grolmsnet.de/kerbtut/
Apache Active Directory Sigle-Sign-On
abstract
This tutorial contains my knowledge about using Apache/mod_auh_kerb and Windows 2000/2003/2008R2 as KDC.
-
Preface
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:
- User has to type his password only once (when logging into his Windows Machine)
- No password is sent to the webserver. Instead the browser sends a service ticket that is checked by the webserver
Overwiew of webclients and webservers supporting 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. -
Prerequirements
-
of knowledge:
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:
- Brian Tung’s The Moron’s Guide to Kerberos
- The comp.protocols.kerberos Kerberos FAQ
- Brian Tung’s excellent book “Kerberos: A Network Authentication System” ISBN: 0201379244
- RFC 4120 – The Kerberos Network Authentication Service (V5) (obsoletes RFC 1510)
In detail I expect you to be familiar with:
-
what is a “Key Distribution Center” (KDC)
(“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)”)
-
what is a “principal”
(a principal is someone or something you authenticate or authenticate to)
Types of principals are
- user-principalsKerberos representation of people sitting at a machine. Example: fredegar@GROLMSNET.DE)
- service-principals. e.g. Kerberos representation of a webserver. Example: HTTP/beren.grolmsnet.de@GROLMSNET.DE
-
keytab file
on a kerberized host it holds the keys of service-principals
-
/etc/krb5.conf file
configuration of Kerberosinstallation, see man krb5.conf
-
ktutil program
maintains keytabfiles, see man ktutil
-
kinit program
used to start authentication of a principal an to get a “Ticket granting Ticket” (TGT) man kinit
-
the klist program
shows all tickets you got in your ticket cache since you run kinit.man klist
-
of software
- Windows 2000 Server/2003/2008 R2 to act as DC and KDC.
- Window 2000/Window XP/Vista/Windows 7 for your workstations.
- Internet Exploder 8.0, 7.0, 6.0 or 5.5
- A Kerberos implementation like MIT Kerberos or Heimdal
- Apache and mod_auth_kerb
-
-
Example scenario
the elements of our example scenario:
- GROLMSNET.DEis 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!
-
Basic Kerberos configuration of webserverhost beren.grolmsnet.de
- Make sure the clocktime of KDC, workstation and webserver is in sync. I use NTP for that task.
- 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.
-
Test if Kerberos works
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
- ensure that beren can reach KDC ulmo via the network
- have an username and password in Windows Domain GROLMSNET.DE. In this example fredegar is used as username.
- use your shell and type
achim@beren [~]$ kinit fredegar@GROLMSNET.DE
If everything is OK the command will ask you for fredegar‘s domain password and terminates without an error message.
- use klist to show the initial ticket you have got from the KDC:
achim@beren [~]$ klist
-
Creating the HTTP service principal for beren.grolmsnet.de
For every kerberized host you have to create a service principal on the KDC.When using Windows 2000 that means you have to
- create a dummyaccount in Windows Domain GROLMSNET.DE. It is used like a machine account. In this example the name of dummyaccount is kerbdummy1.
- login to the DC ulmo and use the Windows commandline tool ktpass to map the dummyaccount kerbdummy1 to the serviceprincipal HTTP/beren.grolmsnet.de@GROLMSNET.DE. You need that serviceprincipal to kerberize host beren.
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 keytabfilec:\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
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 possible prefer RC4 over DES because the experts say (I am no one) DES is weak.
If you want to kerberize additional hosts you need to create one dummyaccount an run ktpass per kerberized host.
-
preparing the keytabfile
- 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.
-
mod_auth_kerb
- 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.
- Platforms like Solaris or FreeBSD don’t ship with GNU-make as default make.
- 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.
-
KrbMethodNegotiate
controls if your Apache uses Negotiate GSSAPI Keberos authentication. Set this to on, that’s the SSO we want to use 🙂
-
KrbMethodK5Passwd
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.
-
- install Apache with DSO support and mod_auth_kerb as described in INSTALL
-
Internet Exploder
- 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!
-
Debugging
-
Tools
- use the Apache error_log to find out what is going wrong. Don’t forget to adjust the Apache LogLevel in httpd.conf to debug to see ALL error and debugmessages!
- use the eventlog of luthien to find out what is going wrong
- use klist.exe and kerbtray.exe for debugging on Windows 2000 workstation.
- Kerberos eventlogging in Windows can be activated using HOWTO http://support.microsoft.com/default.aspx?scid=kb;en-us;262177
-
Pitfalls
-
Double principal mapping
ktpass nor setspn do a check if a principal is already in use. Mapping a principal to two AD-accounts will stop the DC sending host tickets.
In this case kvno (kgetcred on Heimdal) will print errormessages of kind “.. not found in database…”.- use
setspn -q principalname
to search for all accounts the principal is mapped
- use
setspn -d principalname wrongaccountname
to remove the wrong mapping
- use
-
NT 4.0 accounts
Useraccounts that are not created in Active Directory but were migrated from a predecessor NT 4.0 domain have no Kerberos key (because the key is created from cleartext-password). When changing the password the first time in AD the Kerberos key is created. So changing the account’s password and waiting for AD replicating the data to the KDC you want to authenticate to helps.
-
-
Additional readings and ressources
- Kerberos Documentation for Windows 7, Windows Vista, Windows Server 2008 R2, and Windows Server 2008 (Microsoft)
- Overview of keytabfilestructure (Achim Grolms)
- 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
-
Mailinglists
- modauthkerb-help@lists.sourceforge.net Mailinglist and List archive
- Kerberos Mailinglist archive
- Heimdal-discussion mailinglist archive
-
-
Advanced topics
- configuring WWW-Negotiate and credentialsdelegation (Achim Grolms)
credits
Many thanks to
- Harald Jörg, who contributed the Kerberos knowledge.
- Christopher Odenbach, corrector.
- Jari Ahonen, corrector
- Karsten Künne, KDE and Konqueror
- Pete Rotheroe, who contributed the Windows 2003 testing and knowledge
- Bartosz Radaczyński helped with the kvno stuff
- Volker Wiedmer helped with Windows infrastructure
- Henry B. Hotz gave advice to add the kinit -t test (7.c), Safari-config
- Stefan Kanthak checked and corrected the links
- Yves Martin added Subversion to “clients” section
- Markus Moeller added the RC4-enctype related stuff and msktutil
- Francis Giraldeau helped to correct the -mapuser option
- Björn Klages helped debugging double mapping with setspn
Author: Achim Grolms. Feel free to send me corrections and feedback! modkerbtut@grolmsnet.de
last update 2011-02-07