Using mod_auth_kerb and Windows 2000/2003/2008R2 as KDC

Posted on by phong

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.

 

  1. 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.

  2. Prerequirements

    1. 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:

      1. Brian Tung’s The Moron’s Guide to Kerberos
      2. The comp.protocols.kerberos Kerberos FAQ
      3. Brian Tung’s excellent book “Kerberos: A Network Authentication System” ISBN: 0201379244
      4. RFC 4120 – The Kerberos Network Authentication Service (V5) (obsoletes RFC 1510)

      In detail I expect you to be familiar with:

      1. 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)”)

      2. 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
      3. keytab file

        on a kerberized host it holds the keys of service-principals

      4. /etc/krb5.conf file

        configuration of Kerberosinstallation, see man krb5.conf

      5. ktutil program

        maintains keytabfiles, see man ktutil

      6. kinit program

        used to start authentication of a principal an to get a “Ticket granting Ticket” (TGT) man kinit

      7. the klist program

        shows all tickets you got in your ticket cache since you run kinit.man klist

    2. 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

  3. Example scenario

    overview of scenariothe 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!

  4. 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.

  5. 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

  6. 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

    1. create a dummyaccount in Windows Domain GROLMSNET.DE. It is used like a machine account. In this example the name of dummyaccount is kerbdummy1.
    2. 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.

    3. 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.

  7. preparing the keytabfile

    1. 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)
    2. Make /usr/local/apache/conf/http_beren.krb5keytab readable (chmod 400) for the user that owns the httpd process.
    3. 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.

  8. mod_auth_kerb

    1. 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.
    2. 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.

  9. 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!

  10. Debugging

    • Tools
    • 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

      • 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
    • Mailinglists

  11. Advanced topics

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

Written by phong

View all author posts →

View Larger Map