changeset 278 77b380ba9d84
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/components/apache2/mod_auth_gss/README	Thu Jun 02 00:54:08 2011 -0700
@@ -0,0 +1,122 @@
+Instructions on testing the negotiateauth
+mozilla extension with Apache.
+mod_auth_gss (originally from is an 
+Apache module designed to provide GSSAPI authentication to the Apache 
+web server. Using the "Negotiate" Auth mechanism, which performs full 
+Kerberos authentication based on ticket exchanges and does not require 
+users to insert their passwords to the browser.  In order to use the
+Negotiate method you need a browser supporting it (currently standard IE6.0 or
+Mozilla with the negotiateauth extension). 
+The Negotiate mechanism can be only used with Kerberos v5. The module supports 
+both 1.x and 2.x versions of Apache.
+The use of SSL encryption is also recommended (but not required) if you are 
+using the Negotiate method.
+Installing mod_auth_gss
+* Apache server installed.
+  Both 1.x and 2.x series of Apache are supported (make sure the apache
+  installation contains the apxs command)
+  In Solaris - the necessary Apache 2.X libraries and headers are 
+  usually found in /usr/apache2.
+* Working C compiler.
+* GSSAPI library (Solaris - /usr/lib/
+1. Building the Apache module is simple.
+   Find the directory with the source code and Makefile for
+   $ make
+2. Installing the Apache module requires 'root' privilege.
+   # cp /usr/apache2/libexec
+3. Configure apache to use the new module.
+   Add following line to /etc/apache2/httpd.conf:
+   LoadModule	auth_gss_module	libexec/
+4. Set permissions on the newly created keytab file so that only the
+   apache owner can read the file.  For example, if the apache server
+   is configured to run as user "nobody":
+   $ chown nobody /var/apache2/http.keytab
+   $ chmod 400 /var/apache2/http.keytab
+5. Create a directory in the apache 'htdocs' tree that will be used
+   to test the GSSAPI/KerberosV5 authentication.
+   $ mkdir /var/apache2/htdocs/krb5
+6. Create a ".htaccess" file for the Kerberos directory (step 4),
+   it should contain the following entries:
+	AuthType GSSAPI
+	AuthGSSServiceName HTTP
+        AuthGSSKeytabFile /var/apache2/http.keytab
+        AuthGssDebug 1
+   * AuthGssDebug is only needed for testing purposes, it causes extra
+     DEBUG level messages to be displayed in the Apache error_log file
+     (/var/apache2/logs/error_log).
+7. Put some content in the Kerberos web directory so the tester can
+   verify that they accessed the page correctly.
+8. Set the "AllowOverride" parameter in /etc/apache2/httpd.conf
+   to "All" for the Kerberos directory created in step 5.
+<Location "/var/apache2/htdocs/krb5">
+    Options Indexes FollowSymLinks MultiViews
+    AllowOverride All
+    Require valid-user
+Configurating Kerberos
+1. Set up Kerberos Server (if you don't already have one).
+   Follow basic instructions given at  Search for
+   "Configuring Kerberos" in the 
+   "Solaris Administration Guide: Security Services" book.
+   - The KDC should be a protected, standalone system.  But for 
+     internal testing purposes it may be hosted on the same system 
+     as the Apache web server.
+2. Create a Kerberos service key for the Apache server to use for
+   authenticating the clients.  Also create a user principal testing
+   the browser later.
+   The "Negotiate" method used by IIS and IE is "HTTP/<hostname>@REALM".
+   To create this principal for use with the Apache module do the following:
+   [ As 'root', on the Apache server ]
+   a.  /usr/sbin/kadmin
+      - this assumes the KDC setup procedure was followed (step 1).
+   b. kadmin: addprinc -randkey HTTP/<fully_qualified_host_name>
+   c. kadmin: ktadd -k /var/apache2/http.keytab HTTP/<fully_qualified_host_name>
+   d. kadmin: addprinc tester
+   e. kadmin: quit
+Testing the 'Negotiate' plugin with mozilla:
+1.  The client system must be configured to use Kerberos.
+    Setup /etc/krb5/krb5.conf to use the KDC created earlier
+2.  'kinit'  to get a TGT as the "tester" principal created
+    above in step 2d.
+    $ kinit tester
+         ( enter password )
+3.  Use mozilla (with 'negotiateauth' extension installed)
+    to access the Kerberos protected page (created above 
+    in steps 4-6).
+    If the pages do not show up, its probably due to
+    a misconfigured Kerberos configuration on the client
+    or the server (or both).  There is very little that
+    needs to be done for Mozilla or apache.