welcome hpws docs hp-ux webservers home contact hp support
hp logo - invent  hp-ux web server suite

Admin Guide for Mod_auth_kerb


Overview - Sub-topic Title Configuration - Default Configuration for mod_auth_kerb - Supported mod_auth_kerb directives - Steps to configure mod_auth_kerb Troubleshooting Legal Notices NOTE: Much of the information in this document has been taken from the modauthkerb.sourceforge.org site: http://modauthkerb.sourceforge.net/index.html


Mod_auth_kerb 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 supports kerberos5 protocol for password verification. 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, it is advisable to use mod_ssl.


Default Configuration for mod_auth_kerb AuthType Kerberos AuthName "Kerberos Login" KrbMethodNegotiate on KrbAuthoritative on KrbVerifyKDC off KrbAuthRealm SERVERNAME.COM KrbServiceName HTTP Krb5Keytab /etc/krb5.keytab KrbMethodNegotiate on KrbSaveCredentials off KrbMethodK5Passwd on <Limit GET POST> require valid-user </Limit> Summary of Supported Directives AuthType type For Kerberos authentication to work, AuthType must be set to Kerberos For the reasons of backwards compatibility the value KerberosV5 is also supported. Its use is not recommended though. KrbMethodK5Passwd on | off (set to on by default) To enable or disable the use of password based authentication for Kerberos v5, set the KrbMethodK5Passwd directive to either o n or off. KrbAuthoritative on | off (set to on by default) If set to off, this directive allows authentication controls to be passed to another modules. KrbAuthRealms realm1 [realm2, realm3,... realmN] This option takes one or more arguments (separated by spaces), specifying the Kerberos realm(s) to be used for authentication. The default realm is taken from the local Kerberos configuration. KrbVerifyKDC on | off (set to on by default) Use this option to disable the verification tickets against local keytab to prevent KDC spoofing attacks. Use this only for testing purposes. KrbServiceName service (set to HTTP by default) To specify the service name that will be used by Apache for authentication, store the corresponding key of this name in the keytab. Krb5Keytab /path/to/keytab Use this option to specify the location of the Kerberos V5 keytab file. If unspecified, it takes the "default keytab" from Kerberos V5's configuration file. 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 the ticket file or credential cache s needed after a user authenticates, normally for cgi scripts. If you turn on KrbSaveCredentials, the tickets are retrieved into a ticket file or credential cache and will be made available for the request handler. The ticket file is removed after request is handled. A CGI script can use these files by setting the KRB5CCNAME (v5) environment variable to point to the filename as listed above. Steps to configure mod_auth_kerb Before starting configuring the module, make sure your Kerberos environment is configured (that is, KDC, /etc/krb5.conf, and others.). Use the kinit command from the Apache system to get a ticket for known principal (preferably the user who tests the module). 1.Create a service key needed to perform client authentication for the module. Verification of the kerberos password has two steps. a. The KDC is contacted using the password trying to receive a ticket for the client. b. After this ticket is successfuly acquired, the module must also verify that KDC has not been deliberately faked and the ticket just received can be trusted. If this check is not performed, any attacker capable of spoofing the KDC can 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, that Apache shares with the KDC. This service key must be created during configuration the module. The 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 readable for the Apache process and should contain the key used for www authentication. In order load the module when Apache starts, add the following line to the httpd.conf file: LoadModule auth_kerb_module libexec/mod_auth_kerb.so CONFIGURING KERBEROS Following are the steps to configure Kerberos. 1) Install Apache ( onwards) with mod_auth_kerb support. 2) Create the file /etc/krb5.conf with the following contents: # # Kerberos configuration # # see krb5.conf(4) for more details # [libdefaults] default_realm = SERVERNAME.COM default_tkt_enctypes = DES-CBC-MD5 default_tgs_enctypes = DES-CBC-MD5 ccache_type = 2 [realms] SERVERNAME.COM = { kdc = servername.com:88 admin_server = servername.com } [domain_realm] .yourorg.com = SERVERNAME.COM [logging] kdc = FILE:/var/log/krb5kdc.log admin_server = FILE:/var/log/kadmin.log default = FILE:/var/log/krb5lib.log 3) On HP-UX 11.00 and 11.11 copy this file to /usr/etc directory. # cp /etc/krb5.conf /usr/etc/krb5.conf 4) Configure your Kerberos Environment. 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, the 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 type of KDC server used. From the www system start the kadmin command, connect to the KDC and create principal HTTP/servername@REALM with a random key. Then extract the key into a local keytab and change ownership and permissions for the keytab file so that only the Apache user can access it. 5) Verify krb5 on the server host. Before starting configuring the module, make sure your Kerberos environment on the web host is properly configured. Use the kinit command to get a ticket from the KDC. # kinit <principal name> This should prompt for a password which if provided should give you the prompt back without any errors. Then run the klist command. # klist Example: # kinit <principalname> Password for <principalname>@SERVERNAME.COM: # klist Ticket cache: FILE:/tmp/krb5cc_31597 Default principal: <principalname>@SERVERNAME.COM Valid starting Expires Service principal 05/26/06 14:23:50 05/27/06 00:26:27 krbtgt/SERVERNAME.COM@SERVERNAME.COM The above message is displayed only if the Kerberos installation is successful. 6) Configure mod_auth_kerb Ensure that Apache works as expected. Load the mod_auth_kerb module. To do this, uncomment the LoadModule statement for mod_auth_kerb. 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 corresponding directory. A basic configuration is already provided in httpd.conf. <Directory /var/www> AuthType Kerberos AuthName "Kerberos Login" KrbMethodNegotiate off KrbAuthoritative on KrbVerifyKDC off KrbAuthRealm DINO.INDIA.HP.COM KrbServiceName HTTP Krb5Keytab /etc/krb5.keytab KrbMethodNegotiate on KrbSaveCredentials off KrbMethodK5Passwd on <Limit GET POST> require valid-user </Limit> </Directory> Modify SERVERNAME.COM with the name of the Kerberos Server for the KrbAuthRealm directive. Also change the directory "/var/www" to the directory for which the Kerberos authentication is required. 7) Configure the browsers. For password based authentication, browsers supporting the Basic HTTP authentication method can be used without any change. In order to use ticket based authentication (Negotiate) you will need either MS Internet Explorer 5.0+ running on Win2000 SP2 (or later) or Mozilla with the Negotiateauth extension (available in 1.7beta and later). Configuring 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. For more information on configuring a Microsoft Windows System to use Unix KDC, see http://www.microsoft.com/windows2000/techinfo/planning/security/kerbsteps.asp Configuting Mozilla Ensure that your Mozilla distribution contains the Negotiateauth component (libnegotiateauth.so on Unix, negotiateauth.dll on Windows). Generally this is included in versions 1.7beta and later on Unix platforms including Mac OSX, maybe 1.8 and later on Windows.) 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 placed by Apache in the REMOTE_USER environment variable so that it could be used by cgi-bin scripts. 8) Restart Apache. # /opt/hpws/apache/bin/apachectl restart 9) Go to the browser you have configured and access the directory as specified in the httpd.conf file. This should prompt you for UserName and Passwd for Kerberos authentication. Provide the same username and password as given during Kerberos environment setup. This should let you see the directory on authentication. On specifying any other password access should be denied. Note: If you want to use ssl then # /opt/hpws/apache/bin/apachectl startssl


1) Check if your Kerberos environment is set up properly. This can be done using kinit and klist commands. This should give you the tickets. See section "Steps to configure mod_auth_kerb". 2) Ensure that the /etc/krb5.conf file is correct. 3) For HP-UX 11.00 and 11.11, check for the file /usr/etc/krb5.conf 4) Check the error_log with debug option on in httpd.conf. Change the line LogLevel warn To LogLevel debug and check the file /opt/hpws/apache/logs/error_log for the errors. ***************************************************************************