--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/components/apache24/mod_auth_gss/README Wed Feb 25 02:02:14 2015 -0800
@@ -0,0 +1,122 @@
+Instructions on testing the negotiateauth
+mozilla extension with Apache.
+
+Introduction
+-----------------
+mod_auth_gss (originally from http://modauthkerb.sourceforge.net/) 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
+------------------------
+
+Prerequisites
+* 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/libgss.so.1)
+
+1. Building the Apache module is simple.
+ Find the directory with the source code and Makefile for
+ mod_auth_gss.so.
+ $ make
+
+2. Installing the Apache module requires 'root' privilege.
+ # cp mod_auth_gss.so /usr/apache2/libexec
+
+3. Configure apache to use the new module.
+ Add following line to /etc/apache2/httpd.conf:
+ LoadModule auth_gss_module libexec/mod_auth_gss.so
+
+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.
+Ex:
+<Location "/var/apache2/htdocs/krb5">
+ Options Indexes FollowSymLinks MultiViews
+ AllowOverride All
+ Require valid-user
+</Location>
+
+Configurating Kerberos
+-----------------------
+
+1. Set up Kerberos Server (if you don't already have one).
+ Follow basic instructions given at docs.sun.com. 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.
+