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 Building and installing the module
  23 ----------------------------------
  24 see INSTALL
  25
  26 Summary of Supported Directives
  27 -------------------------------
  28
  29 AuthType type
  30    For Kerberos authentication to work, AuthType must be set to 'Kerberos'. For
  31    the reasons of backwards compatibility the values KerberosV4 and KerberosV5
  32    are also supported. Their use is not recommended though, for finer setting
  33    use following three options.
  34
  35
  36 KrbMethodNegotiate on | off     (set to on by default)
  37    To enable or disable the use of the Negotiate method. You need a special
  38    support on the browser side to support this mechanism.
  39
  40 KrbMethodK5Passwd on | off      (set to on by default)
  41    To enable or disable the use of password based authentication for Kerberos
  42    v5.
  43
  44 KrbMethodK4Passwd on | off      (set to on by default)
  45    To enable or disable the use of password based authentication for Kerberos
  46    v4.
  47
  48 KrbAuthoritative on | off       (set to on by default)
  49    If set to off this directive allow authentication controls to be pass on to
  50    another modules. Use only if you really know what you are doing.
  51
  52 KrbAuthRealms realm1 [realm2 ... realmN]
  53    This option takes one or more arguments (separated by spaces), specifying
  54    the Kerberos realm(s) to be used for authentication. This defaults to the
  55    default realm taken from the local Kerberos configuration.
  56
  57 KrbVerifyKDC on | off           (set to on by default)
  58    This option can be used to disable the verification tickets against local
  59    keytab to prevent KDC spoofing atacks. It should be used only for testing
  60    purposes. You have been warned.
  61
  62 KrbServiceName server_principal
  63    Specifies a principal name to use by Apache when authenticating the clients.
  64    By default value of the form
  65         HTTP/<FQDN_of_apache>@<realm>
  66    is used. The FQDN part can contain any hostname and can be used to work
  67    around problems with misconfigured DNS. A corresponding key of this name
  68    must be stored in the keytab.
  69    If this option is set to 'Any', then any prinicpal from the keytab which
  70    matches the client's request may be used.
  71
  72 Krb4Srvtab /path/to/srvtab
  73    This option takes one argument, specifying the path to the Kerberos V4
  74    srvtab. It will simply use the "default srvtab" from Kerberos V4's
  75    configuration if this option is not specified. The srvtab must be readable
  76    for the apache process, and should be different from srvtabs containing keys
  77    for other services.
  78
  79 Krb5Keytab /path/to/keytab
  80    This option takes one argument, specifying the location of the Kerberos V5
  81    keytab file. It will use the "default keytab" from Kerberos V5's config if
  82    it is not specified here. The keytab file must be readable for the apache
  83    process, and should be different from other keytabs in the system.
  84
  85 KrbSaveCredentials on | off     (set to off by default)
  86    This option enables credential saving functionality.
  87
  88 KrbDelegateBasic on | off       (set to off by default)
  89    If set to 'on' this options causes that Basic authentication is always
  90    offered regardless setting the KrbMethodK[45]Pass directives. Then, if
  91    a Basic authentication header arrives authentication decision is passed
  92    along to another modules. This option is a work-around for insufficient
  93    authentication scheme in Apache (Apache 2.1 seems to provide better support
  94    for multiple various authentication mechanisms).
  95
  96 KrbLocalUserMapping on | off    (set to off by default)
  97    When enabled, modul will try to translate authenticated username to local
  98    name, which can be used by applications requiring an environment-specific
  99    name (e.g. user account name). Simply, the realm name will be stripped out.
 100
 101 Note on server principals
 102 -------------------------
 103 Now you have to create an service key for the module, which is needed to
 104 perform client authentication. Verification of the kerberos password has two
 105 steps. In the first one the KDC is contacted using the password trying to
 106 receive a ticket for the client. After this ticket is sucessfuly acquired, the
 107 module must also verify that KDC hasn't been deliberately faked and the ticket
 108 just received can be trusted. If this check would haven't been done any
 109 attacker capable of spoofing the KDC could impersonate any principal registered
 110 with the KDC. In order to do this check the apache module must verify that the
 111 KDC knows its service key, which the apache shares with the KDC. This service
 112 key must be created during configuration the module. This service key is also
 113 needed when the Negotiate method is used. In this case the module acts as a
 114 standard kerberos service (similarly to e.g. kerberized ssh or ftp servers).
 115 Default name of the service key is HTTP/<fqdn_of_www_server>@REALM, another
 116 name of the first instance can be set using the KrbServiceName option. The key
 117 must be stored in a keytab on a local disk, the Krb5Keytab and Krb4Srvtab
 118 options are used to specify the filename with the keytab. This file should be
 119 only readable for the apache process and contain only the key used for www
 120 authentication.
 121
 122 Ticket File/Credential Cache Saving
 123 -----------------------------------
 124 Sometimes there is need to keep the ticket file or credential cache around
 125 after a user authenticates, normally for cgi scripts. If you turn on
 126 KrbSaveCredentials, the tickets will be retrieved into a ticket file or
 127 credential cache that will be available for the request handler. The ticket
 128 file will be removed after request is handled.
 129
 130 $Id$