README

   1 Mod_auth_kerb (http://modauthkerb.sourceforge.net/) is an Apache module
   2 designed to provide Kerberos authentication to the Apache web server. Using the
   3 Basic Auth mechanism, it retrieves a username/password pair from the browser
   4 and checks them against a Kerberos server as set up by your particular
   5 organization. The module also supports the Negotiate authentication method,
   6 which performs full Kerberos authentication based on ticket exchanges, and does
   7 not require users to insert their passwords to the browser. In order to use the
   8 Negotiate method you need a browser supporting it (currently standard IE6.0 or
   9 Mozilla with the negotiateauth extension (http://negotiateauth.mozdev.org/).
  10
  11 The module supports both kerberos4 and kerberos5 protocols for password
  12 verification. The Negotiate mechanism can be only used with Kerberos v5. The
  13 module supports both 1.x and 2.x versions of Apache.
  14
  15 If you are using the Basic Auth mechanism, the module does not do any special
  16 encryption of any sort. The passing of the username and password is done with
  17 the same Base64 encoding that Basic Auth uses. This can easily be converted to
  18 plain text. To counter this, I would suggest also using mod_ssl or Apache-SSL.
  19 The use of SSL encryption is also recommended if you are using the Negotiate
  20 method.
  21
  22 Installing mod_auth_kerb
  23 ------------------------
  24
  25 Prerequisites
  26
  27     * Development enviroment (i.e. libraries and header files) for Kerberos5
  28       and/or Kerberos4.
  29       The module is known to work with the MIT Kerberos implementation
  30       (supporting both krb4 and krb5), the kth-krb Kerberos4 implementation,
  31       and the Heimdal Kerberos5 implementation. The Kerberos installation on
  32       your system should contain the krb4-config and/or krb5-config command(s).
  33     * Apache server installed.
  34       Both 1.x and 2.x series of Apache are supported (make sure the apache
  35       installation contains the apxs command)
  36     * Working C compiler, GNU make.
  37     * The latest source of the module available from the main project site
  38       (http://sourceforge.net/project/showfiles.php?group_id=51775).
  39
  40 You will also need to have an working Kerberos enviroment, of course.
  41
  42 Building and installing the module
  43
  44 Unpack the distribution tarball and run the configure script. The script looks for krb5 and krb4 libraries and headers and then for an Apache installation directory. You can use following flags to specify locations of these files:
  45
  46     * --with-krb4=
  47       --with-krb5=
  48       these options are used to specify locations of the installation
  49       directories for krb4 and krb5, respectively. If you don't want to
  50       compile support for one of the method, use no as the appropriate
  51       parameter.
  52     * --with-apache=
  53       use this parameter to specify location where the Apache installation
  54       resides.
  55
  56 After the configuration script finishes run make followed by make install. You
  57 will need to have writing permission for the apache directory in order to
  58 install the module. An example of the building stage follows:
  59
  60   ./configure --with-krb5=/software/krb5-1.3.1          \
  61               --with-krb4=no                            \
  62               --with-apache=/software/apache-2.0.47
  63   make
  64   su
  65   make install
  66
  67 After installing the module you have to adapt the apache configuration. See
  68 this page for detailed information on configuration.  You can submit any
  69 comment, questions, bugs etc. via the project page.
  70
  71
  72 Configuration
  73 -------------
  74
  75 Before starting configuring the module make sure your Kerberos enviroment is
  76 properly configured (i.e. KDC, /etc/krb5.conf, etc.). The easiest way to check
  77 is using the kinit command from the apache machine to get a ticket for some
  78 known principal (preferably that one who will be used to test the module).
  79
  80 Now you have to create an service key for the module, which is needed to
  81 perform client authentication. Verification of the kerberos password has two
  82 steps. In the first one the KDC is contacted using the password trying to
  83 receive a ticket for the client. After this ticket is sucessfuly acquired, the
  84 module must also verify that KDC hasn't been deliberately faked and the ticket
  85 just received can be trusted. If this check would haven't been done any
  86 attacker capable of spoofing the KDC could impersonate any principal registered
  87 with the KDC. In order to do this check the apache module must verify that the
  88 KDC knows its service key, which the apache shares with the KDC. This service
  89 key must be created during configuration the module. This service key is also
  90 needed when the Negotiate method is used. In this case the module acts as a
  91 standard kerberos service (similarly to e.g. kerberized ssh or ftp servers).
  92 Default name of the service key is HTTP/<fqdn_of_www_server>@REALM, another
  93 name of the first instance can be set using the KrbServiceName option. The key
  94 must be stored in a keytab on a local disk, the Krb5Keytab and Krb4Srvtab
  95 options are used to specify the filename with the keytab. This file should be
  96 only readable for the apache process and contain only the key used for www
  97 authentication.
  98
  99 In order to get the module loaded on start of apache add following line to your
 100 httpd.conf:
 101
 102         LoadModule      auth_kerb_module        libexec/mod_auth_kerb.so
 103
 104 Summary of Supported Directives
 105
 106 AuthType type
 107    For Kerberos authentication to work, AuthType must be set to 'Kerberos'. For
 108    the reasons of backwards compatibility the values KerberosV4 and KerberosV5
 109    are also supported. Their use is not recommended though, for finer setting
 110    use following three options.
 111
 112
 113 KrbMethodNegotiate on | off     (set to on by default)
 114    To enable or disable the use of the Negotiate method. You need a special
 115    support on the browser side to support this mechanism.
 116
 117 KrbMethodK5Passwd on | off      (set to on by default)
 118    To enable or disable the use of password based authentication for Kerberos
 119    v5.
 120
 121 KrbMethodK4Passwd on | off      (set to on by default)
 122    To enable or disable the use of password based authentication for Kerberos
 123    v4.
 124
 125 KrbAuthoritative on | off       (set to on by default)
 126    If set to off this directive allow authentication controls to be pass on to
 127    another modules. Use only if you really know what you are doing.
 128
 129 KrbAuthRealms realm1 [realm2 ... realmN]
 130    This option takes one or more arguments (separated by spaces), specifying
 131    the Kerberos realm(s) to be used for authentication. This defaults to the
 132    default realm taken from the local Kerberos configuration.
 133
 134 KrbVerifyKDC on | off           (set to on by default)
 135    This option can be used to disable the verification tickets against local
 136    keytab to prevent KDC spoofing atacks. It should be used only for testing
 137    purposes. You have been warned.
 138
 139 KrbServiceName service          (set to HTTP by default)
 140    For specification the service name that will be used by Apache for
 141    authentication. Corresponding key of this name must be stored in the keytab.
 142
 143 Krb4Srvtab /path/to/srvtab
 144    This option takes one argument, specifying the path to the Kerberos V4
 145    srvtab. It will simply use the "default srvtab" from Kerberos V4's
 146    configuration if this option is not specified. The srvtab must be readable
 147    for the apache process, and should be different from srvtabs containing keys
 148    for other services.
 149
 150 Krb5Keytab /path/to/keytab
 151    This option takes one argument, specifying the location of the Kerberos V5
 152    keytab file. It will use the "default keytab" from Kerberos V5's config if
 153    it is not specified here. The keytab file must be readable for the apache
 154    process, and should be different from other keytabs in the system.
 155
 156 KrbSaveCredentials on | off     (set to off by default)
 157    This option enables credential saving functionality.
 158
 159 Ticket File/Credential Cache Saving
 160    Sometimes there is need to keep the ticket file or credential cache around
 161    after a user authenticates, normally for cgi scripts. If you turn on
 162    KrbSaveCredentials, the tickets will be retrieved into a ticket file or
 163    credential cache that will be available for the request handler. The ticket
 164    file will be removed after request is handled.
 165
 166    A CGI script can use these files by setting the KRB5CCNAME (v5) or KRBTKFILE
 167    (v4) environment variables to point to the filename as listed above. A
 168    sample script to use the KRB5CCNAME is here.
 169
 170 Sample .htaccess
 171
 172         AuthType Kerberos
 173         AuthName "Kerberos Login"
 174         KrbAuthRealms KRB.NCSU.EDU NCSU.EDU
 175         KrbMethodK4Passwd off
 176         require principal1@KRB.NCSU.EDU principal2@NCSU.EDU
 177
 178 Reminder, you need to set the appropriate AllowOverride directive in your
 179 server access configuration so that a different AuthType will be allowed.
 180
 181 $Id$