components/web/apache24/mod_auth_gss/README

   1 Instructions on testing the negotiateauth
   2 mozilla extension with Apache.
   3
   4 Introduction
   5 -----------------
   6 mod_auth_gss (originally from http://modauthkerb.sourceforge.net/) is an
   7 Apache module designed to provide GSSAPI authentication to the Apache
   8 web server. Using the "Negotiate" Auth mechanism, which performs full
   9 Kerberos authentication based on ticket exchanges and does not require
  10 users to insert their passwords to the browser.  In order to use the
  11 Negotiate method you need a browser supporting it (currently standard IE6.0 or
  12 Mozilla with the negotiateauth extension).
  13
  14 The Negotiate mechanism can be only used with Kerberos v5. The module supports
  15 both 1.x and 2.x versions of Apache.
  16
  17 The use of SSL encryption is also recommended (but not required) if you are
  18 using the Negotiate method.
  19
  20 Installing mod_auth_gss
  21 ------------------------
  22
  23 Prerequisites
  24 * Apache server installed.
  25   Both 1.x and 2.x series of Apache are supported (make sure the apache
  26   installation contains the apxs command)
  27   In Solaris - the necessary Apache 2.X libraries and headers are
  28   usually found in /usr/apache2.
  29 * Working C compiler.
  30 * GSSAPI library (Solaris - /usr/lib/libgss.so.1)
  31
  32 1. Building the Apache module is simple.
  33    Find the directory with the source code and Makefile for
  34    mod_auth_gss.so.
  35    $ make
  36
  37 2. Installing the Apache module requires 'root' privilege.
  38    # cp mod_auth_gss.so /usr/apache2/libexec
  39
  40 3. Configure apache to use the new module.
  41    Add following line to /etc/apache2/httpd.conf:
  42    LoadModule   auth_gss_module libexec/mod_auth_gss.so
  43
  44 4. Set permissions on the newly created keytab file so that only the
  45    apache owner can read the file.  For example, if the apache server
  46    is configured to run as user "nobody":
  47
  48    $ chown nobody /var/apache2/http.keytab
  49    $ chmod 400 /var/apache2/http.keytab
  50
  51 5. Create a directory in the apache 'htdocs' tree that will be used
  52    to test the GSSAPI/KerberosV5 authentication.
  53    $ mkdir /var/apache2/htdocs/krb5
  54
  55 6. Create a ".htaccess" file for the Kerberos directory (step 4),
  56    it should contain the following entries:
  57         AuthType GSSAPI
  58         AuthGSSServiceName HTTP
  59         AuthGSSKeytabFile /var/apache2/http.keytab
  60         AuthGssDebug 1
  61
  62    * AuthGssDebug is only needed for testing purposes, it causes extra
  63      DEBUG level messages to be displayed in the Apache error_log file
  64      (/var/apache2/logs/error_log).
  65
  66 7. Put some content in the Kerberos web directory so the tester can
  67    verify that they accessed the page correctly.
  68
  69 8. Set the "AllowOverride" parameter in /etc/apache2/httpd.conf
  70    to "All" for the Kerberos directory created in step 5.
  71 Ex:
  72 <Location "/var/apache2/htdocs/krb5">
  73     Options Indexes FollowSymLinks MultiViews
  74     AllowOverride All
  75     Require valid-user
  76 </Location>
  77
  78 Configurating Kerberos
  79 -----------------------
  80
  81 1. Set up Kerberos Server (if you don't already have one).
  82    Follow basic instructions given at docs.sun.com.  Search for
  83    "Configuring Kerberos" in the
  84    "Solaris Administration Guide: Security Services" book.
  85
  86    - The KDC should be a protected, standalone system.  But for
  87      internal testing purposes it may be hosted on the same system
  88      as the Apache web server.
  89
  90 2. Create a Kerberos service key for the Apache server to use for
  91    authenticating the clients.  Also create a user principal testing
  92    the browser later.
  93    The "Negotiate" method used by IIS and IE is "HTTP/<hostname>@REALM".
  94    To create this principal for use with the Apache module do the following:
  95    [ As 'root', on the Apache server ]
  96    a.  /usr/sbin/kadmin
  97       - this assumes the KDC setup procedure was followed (step 1).
  98    b. kadmin: addprinc -randkey HTTP/<fully_qualified_host_name>
  99    c. kadmin: ktadd -k /var/apache2/http.keytab HTTP/<fully_qualified_host_name>
 100    d. kadmin: addprinc tester
 101    e. kadmin: quit
 102
 103 Testing the 'Negotiate' plugin with mozilla:
 104 --------------------------------------------
 105
 106 1.  The client system must be configured to use Kerberos.
 107     Setup /etc/krb5/krb5.conf to use the KDC created earlier
 108
 109 2.  'kinit'  to get a TGT as the "tester" principal created
 110     above in step 2d.
 111     $ kinit tester
 112          ( enter password )
 113
 114 3.  Use mozilla (with 'negotiateauth' extension installed)
 115     to access the Kerberos protected page (created above
 116     in steps 4-6).
 117
 118     If the pages do not show up, its probably due to
 119     a misconfigured Kerberos configuration on the client
 120     or the server (or both).  There is very little that
 121     needs to be done for Mozilla or apache.
 122