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