--- /dev/null
+1. Prerequisites
+----------------
+ - Development enviroment for Kerberos5 and/or Kerberos4 (i.e. libraries and
+ header files). The module works with the MIT Kerberos implementation
+ (supporting both krb4 and krb5), the kth-krb Kerberos4 implementation,
+ and the Heimdal Kerberos5 implementation. Kerberos libraries come with
+ most Linux distributions but they may not be installed by default.
+ - Apache server installed with SSL support.
+ Both 1.x and 2.x series of Apache are supported, provided they are
+ compiled to support DSO. SSL support (provided by either mod_ssl or
+ apache-ssl) is necessary for the module to work in a secure way. Most
+ Linux distributions contain suitable Apache packages.
+ - The latest source of the module available from the main project site
+ (http://sourceforge.net/project/showfiles.php?group_id=51775).
+ - Working C compiler, GNU make.
+
+2. Building and installing the module
+-------------------------------------
+Unpack the distribution tarball and run the configure script to set up the
+build enviroment. The script will try to find krb5 and/or krb4 libraries and
+headers and an Apache installation directory. You can use following flags to
+specify locations of these files:
+
+ --with-krb4=<dir>
+ --with-krb5=<dir>
+ 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 or specify --without-krb5 or --without-krb4.
+ --with-apache=<dir>
+ use this parameter to specify location where the Apache installation
+ resides.
+
+After the configuration script finishes run make followed by make install.
+In order to install the module you will have to have writing permission for
+the apache directory.
+
+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
+
+3. Create the Kerberos principal for the server
+-----------------------------------------------
+A service principal for the web server must be registered with the KDC in
+order to let the module verify users properly. In general the principals for
+web servers have names with format HTTP/servername@REALM, where servername
+is the fully-qualified domain name of the server and REALM is your Kerberos
+realm. If you have multiple virtual servers requiring authentication
+service principals have to be generated for each virtual servername. After
+creating the service principal, corresponding Kerberos keys must be
+extracted to a keytab file stored on the server host. Steps to create the
+principal and extracting the keys vary depending on the KDC server type
+used.
+
+Heimdal or MIT KDC
+------------------
+From the www machine start the kadmin command, connect to the KDC and create
+principal HTTP/servername@REALM with a random key(s). Then extract the keys
+into a local keytab and change ownership and permissions for the keytab
+file so that only the apache user can access it. Example using kadmin from
+Heimdal:
+ kadmin -p admin@REALM -r REALM ank -r HTTP/servername@REALM
+ kadmin -p admin@REALM -r REALM ext -k /etc/httpd/keytab HTTP/servername@REALM
+ chown nobody /etc/httpd/keytab
+ chmod 600 /etc/httpd/keytab
+
+Windows 2000 Domain Controler
+-----------------------------
+The Kerberos realm in Active Directory is the same as the DNS domain
+name of the AD domain. For example, a Kerberos principal for host
+server.example.com might be "HTTP/server.example.com@EXAMPLE.COM".
+
+To install the principal in AD you first need to create a user account in the
+domain for the server. It makes sense to call this account something
+meaningful, maybe "httpd_servername" so that it is obvious what this account is
+used for. To create the account you can use standard AD tools. Make sure that
+the user account has "Password never expires" set and write down the password
+you set for the account (you will need it later).
+
+If you want to kerberize additional hosts you need to create one user account
+per each kerberized host.
+
+The Kerberos principal is associated with a user account with the ktpass.exe
+tool that is part of the Microsoft Support Tools package. This tools needs to
+be run on a domain controller. To associate a Kerberos principal with a user
+account just run ktpass.exe in a command prompt with appropriate parameters to
+create a keytab file. Full description of the ktpass.exe command can be found
+at http://support.microsoft.com/default.aspx?scid=kb;en-us;324144.
+
+ktpass -out c:\apache.ktab -princ HTTP/server.name@REALM.NAME
+ -pass account_password -mapuser httpd_servername
+
+In the above the c:\apache.ktab is the name of the created keytab file,
+account_passwored is the password you set for the user account and
+httpd_servername is the name of the user account.
+
+You need to copy the keytab file to your web server in a secure way to avoid
+revealing the server key(s). Make sure that the keytab file is owned by the
+apache user and only readable to this user (i.e. the permissions are 600).
+After copying the keytab verify the content using the ktutil tool.
+
+4. Verifying krb5 on the server host
+------------------------------------
+Before starting configuring the module make sure your Kerberos enviroment on
+the web host is properly configured. The easiest way to check is using the
+kinit command to get a ticket from the KDC.
+
+5. Configuring mod_auth_kerb
+----------------------------
+First make sure that Apache works as expected.
+
+You need to load the mod_auth_kerb module. To do this, add a LoadModule
+statement into the appropriate section of httpd.conf file.
+
+LoadModule auth_kerb_module modules/mod_auth_kerb.so
+
+The configuration of mod_auth_kerb can be done per directory. The
+configuration directives can be stored in either a <Directory> section of
+httpd.conf or in a .htaccess file in the coresponding directory. Example of a
+Directory section from httpd.conf:
+
+ <Directory /var/www/private>
+ AuthType Kerberos
+ AuthName "Kerberos Login"
+ Krb5Keytab /etc/apache/apache.keytab
+ KrbAuthRealms EXAMPLE.COM
+ Require valid-user
+ </Directory>
+
+The Krb5Keytab file is the one created as described above in section 3.
+
+Summary of all configuration directives supported by the module can be found in
+README.
+
+6. Configuring the browsers
+---------------------------
+For password based authentication any browser supporting the Basic HTTP
+authentication method can be used without any changes. In order to use
+ticket based authentication (Negotiate) you will need either MS Internet
+Explorer 5.0+ running on Win2000 SP2 (or greater) or Mozilla with the
+Negotiateauth extension (available in 1.7rc2 and greater).
+
+Internet Explorer
+-----------------
+To make the Negotiate authentication work the web server hostname must be
+in Internet Explorer "Local Intranet" security zone and the "Windows
+Integrated Authentication" must be enabled in the IE advanced options.
+
+Mozilla
+-------
+TBD
+(First make sure your Mozilla distribution contains the Negotiateauth component
+check libnegotiate.so
+debugging
+Using with heimdal)
+
+6. Access control
+-----------------
+If you want only particular users to be able to access the secured area, you
+can list their principal names in the appropriate Require directive. They must
+be full Kerberos names, including the REALM part. For example:
+ Require kouril@REALM.COM kouril REALM.CZ
+
+The user's name is put by Apache in the REMOTE_USER environment variable so
+that it could be used by cgi-bin scripts.
+
+$Id$
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
+----------------------------------
+see INSTALL
Summary of Supported Directives
+-------------------------------
AuthType type
For Kerberos authentication to work, AuthType must be set to 'Kerberos'. For
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 user principal1@KRB.NCSU.EDU principal2@NCSU.EDU
+KrbDelegateBasic on | off (set to off by default)
+ If set to 'on' this options causes that Basic authentication is always
+ offered regardless setting the KrbMethodK[45]Pass directives. Then, if
+ a Basic authentication header arrives authentication decision is passed
+ along to another modules. This option is a work-around for insufficient
+ authentication scheme in Apache (Apache 2.1 seems to provide better support
+ for multiple various authentication mechanisms).
-Reminder, you need to set the appropriate AllowOverride directive in your
-server access configuration so that a different AuthType will be allowed.
+Note on server principals
+-------------------------
+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.
-$Id$
+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.
+
+$Id: README,v 1.8 2004/01/13
+14:31:53 kouril Exp $
projects / mod_auth_kerb.cvs / .git / commitdiff