-1. ./configure
-2. make
-3. make install
-4. edit your httpd.conf, eg:
- LoadModule auth_kerb_module libexec/mod_auth_kerb.so
-
- <Directory "/var/www/secure">
- Options Indexes FollowSymLinks
- AuthType Kerberos
- KrbAuthRealms ICS.MUNI.CZ MUNI.CZ
- Krb5Keytab /etc/httpd/keytab
- KrbMethodNegotiate On
- KrbMethodK5Pass On
- require kouril@ICS.MUNI.CZ
- </Directory>
-5. start httpd
+Mod_auth_kerb (http://modauthkerb.sourceforge.net/) is an Apache module
+designed to provide Kerberos authentication to the Apache web server. Using the
+Basic Auth mechanism, it retrieves a username/password pair from the browser
+and checks them against a Kerberos server as set up by your particular
+organization. The module also supports the Negotiate authentication method,
+which performs full Kerberos authentication based on ticket exchanges, and does
+not require users to insert their passwords to the browser. In order to use the
+Negotiate method you need a browser supporting it (currently standard IE6.0 or
+Mozilla with the negotiateauth extension (http://negotiateauth.mozdev.org/).
+
+The module supports both kerberos4 and kerberos5 protocols for password
+verification. The Negotiate mechanism can be only used with Kerberos v5. The
+module supports both 1.x and 2.x versions of Apache.
+
+If you are using the Basic Auth mechanism, the module does not do any special
+encryption of any sort. The passing of the username and password is done with
+the same Base64 encoding that Basic Auth uses. This can easily be converted to
+plain text. To counter this, I would suggest also using mod_ssl or Apache-SSL.
+The use of SSL encryption is also recommended if you are using the Negotiate
+method.
+
+Installing mod_auth_kerb
+------------------------
+
+Prerequisites
+
+ * Development enviroment (i.e. libraries and header files) for Kerberos5
+ and/or Kerberos4.
+ The module is known to work with the MIT Kerberos implementation
+ (supporting both krb4 and krb5), the kth-krb Kerberos4 implementation,
+ and the Heimdal Kerberos5 implementation. The Kerberos installation on
+ your system should contain the krb4-config and/or krb5-config command(s).
+ * Apache server installed.
+ Both 1.x and 2.x series of Apache are supported (make sure the apache
+ installation contains the apxs command)
+ * Working C compiler, GNU make.
+ * The latest source of the module available from the main project site
+ (http://sourceforge.net/project/showfiles.php?group_id=51775).
+
+You will also need to have an working Kerberos enviroment, of course.
+
+Building and installing the module
+
+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:
+
+ * --with-krb4=
+ --with-krb5=
+ these options are used to specify locations of the installation
+ directories for krb4 and krb5, respectively. If you don't want to
+ compile support for one of the method, use no as the appropriate
+ parameter.
+ * --with-apache=
+ use this parameter to specify location where the Apache installation
+ resides.
+
+After the configuration script finishes run make followed by make install. You
+will need to have writing permission for the apache directory in order to
+install the module. An example of the building stage follows:
+
+ ./configure --with-krb5=/software/krb5-1.3.1 \
+ --with-krb4=no \
+ --with-apache=/software/apache-2.0.47
+ make
+ su
+ make install
+
+After installing the module you have to adapt the apache configuration. See
+this page for detailed information on configuration. You can submit any
+comment, questions, bugs etc. via the project page.
+
+
+Configuration
+-------------
+
+Before starting configuring the module make sure your Kerberos enviroment is
+properly configured (i.e. KDC, /etc/krb5.conf, etc.). The easiest way to check
+is using the kinit command from the apache machine to get a ticket for some
+known principal (preferably that one who will be used to test the module).
+
+Now you have to create an service key for the module, which is needed to
+perform client authentication. Verification of the kerberos password has two
+steps. In the first one the KDC is contacted using the password trying to
+receive a ticket for the client. After this ticket is sucessfuly acquired, the
+module must also verify that KDC hasn't been deliberately faked and the ticket
+just received can be trusted. If this check would haven't been done any
+attacker capable of spoofing the KDC could impersonate any principal registered
+with the KDC. In order to do this check the apache module must verify that the
+KDC knows its service key, which the apache shares with the KDC. This service
+key must be created during configuration the module. This service key is also
+needed when the Negotiate method is used. In this case the module acts as a
+standard kerberos service (similarly to e.g. kerberized ssh or ftp servers).
+Default name of the service key is HTTP/<fqdn_of_www_server>@REALM, another
+name of the first instance can be set using the KrbServiceName option. The key
+must be stored in a keytab on a local disk, the Krb5Keytab and Krb4Srvtab
+options are used to specify the filename with the keytab. This file should be
+only readable for the apache process and contain only the key used for www
+authentication.
+
+In order to get the module loaded on start of apache add following line to your
+httpd.conf:
+
+ LoadModule auth_kerb_module libexec/mod_auth_kerb.so
+
+Summary of Supported Directives
+
+AuthType type
+ For Kerberos authentication to work, AuthType must be set to 'Kerberos'. For
+ the reasons of backwards compatibility the values KerberosV4 and KerberosV5
+ are also supported. Their use is not recommended though, for finer setting
+ use following three options.
+
+
+KrbMethodNegotiate on | off (set to on by default)
+ To enable or disable the use of the Negotiate method. You need a special
+ support on the browser side to support this mechanism.
+
+KrbMethodK5Passwd on | off (set to on by default)
+ To enable or disable the use of password based authentication for Kerberos
+ v5.
+
+KrbMethodK4Passwd on | off (set to on by default)
+ To enable or disable the use of password based authentication for Kerberos
+ v4.
+
+KrbAuthoritative on | off (set to on by default)
+ If set to off this directive allow authentication controls to be pass on to
+ another modules. Use only if you really know what you are doing.
+
+KrbAuthRealms realm1 [realm2 ... realmN]
+ This option takes one or more arguments (separated by spaces), specifying
+ the Kerberos realm(s) to be used for authentication. This defaults to the
+ default realm taken from the local Kerberos configuration.
+
+KrbVerifyKDC on | off (set to on by default)
+ This option can be used to disable the verification tickets against local
+ keytab to prevent KDC spoofing atacks. It should be used only for testing
+ purposes. You have been warned.
+
+KrbServiceName service (set to HTTP by default)
+ For specification the service name that will be used by Apache for
+ authentication. Corresponding key of this name must be stored in the keytab.
+
+Krb4Srvtab /path/to/srvtab
+ This option takes one argument, specifying the path to the Kerberos V4
+ srvtab. It will simply use the "default srvtab" from Kerberos V4's
+ configuration if this option is not specified. The srvtab must be readable
+ for the apache process, and should be different from srvtabs containing keys
+ for other services.
+
+Krb5Keytab /path/to/keytab
+ This option takes one argument, specifying the location of the Kerberos V5
+ keytab file. It will use the "default keytab" from Kerberos V5's config if
+ it is not specified here. The keytab file must be readable for the apache
+ process, and should be different from other keytabs in the system.
+
+KrbSaveCredentials on | off (set to off by default)
+ This option enables credential saving functionality.
+
+Ticket File/Credential Cache Saving
+ Sometimes there is need to keep the ticket file or credential cache around
+ after a user authenticates, normally for cgi scripts. If you turn on
+ KrbSaveCredentials, the tickets will be retrieved into a ticket file or
+ credential cache that will be available for the request handler. The ticket
+ file will be removed after request is handled.
+
+ A CGI script can use these files by setting the KRB5CCNAME (v5) or KRBTKFILE
+ (v4) environment variables to point to the filename as listed above. A
+ sample script to use the KRB5CCNAME is here.
+
+Sample .htaccess
+
+ AuthType Kerberos
+ AuthName "Kerberos Login"
+ KrbAuthRealms KRB.NCSU.EDU NCSU.EDU
+ KrbMethodK4Passwd off
+ require principal1@KRB.NCSU.EDU principal2@NCSU.EDU
+
+Reminder, you need to set the appropriate AllowOverride directive in your
+server access configuration so that a different AuthType will be allowed.
+
+$Id$
projects / mod_auth_kerb.git / commitdiff