====================================== Admin Guide for Mod_auth_kerb ====================================== TABLE OF CONTENTS 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 ====================================== OVERVIEW -------------------------------------- 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. ====================================== CONFIGURATION -------------------------------------- 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 require valid-user 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/@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 modules/mod_auth_kerb.so CONFIGURING KERBEROS Following are the steps to configure Kerberos. 1) Install Apache (2.0.58.00 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 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 Password for @SERVERNAME.COM: # klist Ticket cache: FILE:/tmp/krb5cc_31597 Default principal: @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 section of httpd.conf or in a .htaccess file in the corresponding directory. A basic configuration is already provided in httpd.conf. 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 require valid-user 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/hpws22/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/hpws22/apache/bin/apachectl startssl TROUBLESHOOTING -------------------------------------- 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/hpws22/apache/logs/error_log for the errors. *************************************************************************** Legal Notices The information in this document is subject to change without notice. WARRANTY DISCLAIMER HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance or use of this material. RESTRICTED RIGHTS LEGEND Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies. Rights for non-DOD U.S. Government Department and Agencies are as set forth in FAR 52.227-19 (c)(1,2). COPYRIGHT NOTICES Copyright (c) 1998, Regents of the University of California All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the University of California, Berkeley nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. TRADEMARK NOTICES UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. ACKNOWLEDGEMENTS This product includes software developed by the Apache Software Foundation. This documentation is based on information from the Apache Software Foundation (http://www.apache.org).