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

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

<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	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 <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/[email protected]

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 [email protected] 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



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/hpws/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).