Achim Grolms:

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

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:

    Overwiew of webclients and webservers supporting Kerberos authentication:
     mod_auth_kerb Negotiate (GSSAPI Kerberos)IIS Negotiate (GSSAPI SPNEGO Kerberos)
    Internet Explorersince 5.5 on W2K/XPsince 5.5 on W2K/XP
    KDE Konqueror since KDE 3.3.1 since KDE 3.3.1
    Mozilla Firefoxyesyes
    Perl LWP with LWP::Authen::Negotiate yesyes
    Subversion with neon 0.25.5 ?
    Lynxpatch available (Karsten Künne)
    SafariQuoting 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-principals

          Kerberos 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 scenario

    the elements of our example scenario:

    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

  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

  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 DCWindows 2003 SP1 DCWindows 2003 DCWindows 2000 DC
      encryption type RC4 AES256 (not supported by WinXP) RC4DES (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.

    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 KerberosHeimdal
      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 KerberosHeimdal
      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

  10. Debugging

  11. Advanced topics

credits

Many thanks to

Author: Achim Grolms. Feel free to send me corrections and feedback! modkerbtut@grolmsnet.de

last update 2011-02-07