INSTALL

   1 1. Prerequisites
   2 ----------------
   3  - Development enviroment for Kerberos5 and/or Kerberos4 (i.e. libraries and
   4    header files).  The module works with the MIT Kerberos implementation
   5    (supporting both krb4 and krb5), the kth-krb Kerberos4 implementation,
   6    and the Heimdal Kerberos5 implementation. Kerberos libraries come with
   7    most Linux distributions but they may not be installed by default.
   8  - Apache server installed with SSL support.
   9    Both 1.x and 2.x series of Apache are supported, provided they are
  10    compiled to support DSO. SSL support (provided by either mod_ssl or
  11    apache-ssl) is necessary for the module to work in a secure way. Most
  12    Linux distributions contain suitable Apache packages.
  13  - The latest source of the module available from the main project site
  14    (http://sourceforge.net/project/showfiles.php?group_id=51775).
  15  - Working C compiler, GNU make.
  16
  17 2. Building and installing the module
  18 -------------------------------------
  19 Unpack the distribution tarball and run the configure script to set up the
  20 build enviroment. The script will try to find krb5 and/or krb4 libraries and
  21 headers and an Apache installation directory. You can use following flags to
  22 specify locations of these files:
  23
  24    --with-krb4=<dir>
  25    --with-krb5=<dir>
  26       these options are used to specify locations of the installation
  27       directories for krb4 and krb5, respectively. If you don't want to
  28       compile support for one of the method, use no as the appropriate
  29       parameter or specify --without-krb5 or --without-krb4.
  30    --with-apache=<dir>
  31       use this parameter to specify location where the Apache installation
  32       resides.
  33
  34 After the configuration script finishes run make followed by make install.
  35 In order to install the module you will have to have writing permission for
  36 the apache directory.
  37
  38 An example of the building stage follows:
  39    ./configure --with-krb5=/software/krb5-1.3.1         \
  40                --with-krb4=no                           \
  41                --with-apache=/software/apache-2.0.47
  42    make
  43    su
  44    make install
  45
  46 3. Create the Kerberos principal for the server
  47 -----------------------------------------------
  48 A service principal for the web server must be registered with the KDC in
  49 order to let the module verify users properly. In general the principals for
  50 web servers have names with format HTTP/servername@REALM, where servername
  51 is the fully-qualified domain name of the server and REALM is your Kerberos
  52 realm.  If you have multiple virtual servers requiring authentication
  53 service principals have to be generated for each virtual servername.  After
  54 creating the service principal, corresponding Kerberos keys must be
  55 extracted to a keytab file stored on the server host.  Steps to create the
  56 principal and extracting the keys vary depending on the KDC server type
  57 used.
  58
  59 Heimdal or MIT KDC
  60 ------------------
  61 From the www machine start the kadmin command, connect to the KDC and create
  62 principal HTTP/servername@REALM with a random key(s).  Then extract the keys
  63 into a local keytab and change ownership and permissions  for the keytab
  64 file so that only the apache user can access it. Example using kadmin from
  65 Heimdal:
  66   kadmin -p admin@REALM -r REALM ank -r HTTP/servername@REALM
  67   kadmin -p admin@REALM -r REALM ext -k /etc/httpd/keytab HTTP/servername@REALM
  68   chown nobody /etc/httpd/keytab
  69   chmod 400 /etc/httpd/keytab
  70
  71 Windows 2000 Domain Controler
  72 -----------------------------
  73 The Kerberos realm in Active Directory is the same as the DNS domain
  74 name of the AD domain. For example, a Kerberos principal for host
  75 server.example.com might be "HTTP/server.example.com@EXAMPLE.COM".
  76
  77 To install the principal in AD you first need to create a user account in the
  78 domain for the server. It makes sense to call this account something
  79 meaningful, maybe "httpd_servername" so that it is obvious what this account is
  80 used for. To create the account you can use standard AD tools.  Make sure that
  81 the user account has "Password never expires" set and write down the password
  82 you set for the account (you will need it later).
  83
  84 When using ticket based authentication (KrbMethodNegotiate) and also wanting
  85 to save the ticket (KrbSaveCredentials), the user account for the Kerberos
  86 principal must have the option "Account is trusted for delegation" set. This
  87 enables to user account to delegate the tickets to the server for further
  88 authentication.
  89
  90 If you want to kerberize additional hosts you need to create one user account
  91 per each kerberized host.
  92
  93 The Kerberos principal is associated with a user account with the ktpass.exe
  94 tool that is part of the Microsoft Support Tools package. This tools needs to
  95 be run on a domain controller. To associate a Kerberos principal with a user
  96 account just run ktpass.exe in a command prompt with appropriate parameters to
  97 create a keytab file. Full description of the ktpass.exe command can be found
  98 at http://support.microsoft.com/default.aspx?scid=kb;en-us;324144.
  99
 100 ktpass -out c:\apache.ktab -princ HTTP/server.name@REALM.NAME
 101        -pass account_password -mapuser httpd_servername -crypto DES-CBC-MD5
 102
 103 In the above the c:\apache.ktab is the name of the created keytab file,
 104 account_passwored is the password you set for the user account and
 105 httpd_servername is the name of the user account. The DES-CBC-MD5 encryption
 106 is needed to get Heimdal to work with Microsoft KDC, MIT Kerberos does not
 107 seem to need it but it does not hurt either. In fact, RFC1510 discourages
 108 using DES-CBC-CRC (default in Win2k ktpass.exe) so it's probably better to
 109 use DES-CBC-MD5 in all cases.
 110
 111 You need to copy the keytab file to your web server in a secure way to avoid
 112 revealing the server key(s). Note that the copy needs to be done in binary
 113 mode to avoid corrupting the file. Make sure that the keytab file is owned by
 114 the apache user and only readable to this user (i.e. the permissions are 400).
 115 After copying the keytab verify the content using the ktutil tool.
 116
 117 See http://www.grolmsnet.de/kerbtut for more information about using
 118 mod_auth_kerb with Windows KDC.
 119
 120 4. Verifying krb5 on the server host
 121 ------------------------------------
 122 Before starting configuring the module make sure your Kerberos enviroment on
 123 the web host is properly configured. The easiest way to check is using the
 124 kinit command to get a ticket from the KDC.
 125
 126 5. Configuring mod_auth_kerb
 127 ----------------------------
 128 First make sure that Apache works as expected.
 129
 130 You need to load the mod_auth_kerb module. To do this, add a LoadModule
 131 statement into the appropriate section of httpd.conf file.
 132
 133 LoadModule auth_kerb_module modules/mod_auth_kerb.so
 134
 135 The configuration of mod_auth_kerb can be done per directory. The
 136 configuration directives can be stored in either a <Directory> section of
 137 httpd.conf or in a .htaccess file in the coresponding directory. Example of a
 138 Directory section from httpd.conf:
 139
 140   <Directory /var/www/private>
 141      AuthType Kerberos
 142      AuthName "Kerberos Login"
 143      Krb5Keytab  /etc/apache/apache.keytab
 144      KrbAuthRealms EXAMPLE.COM
 145      Require valid-user
 146   </Directory>
 147
 148 The Krb5Keytab file is the one created as described above in section 3.
 149
 150 Summary of all configuration directives supported by the module can be found in
 151 README.
 152
 153 6. Configuring the browsers
 154 ---------------------------
 155 For password based authentication any browser supporting the Basic HTTP
 156 authentication method can be used without any changes. In order to use
 157 ticket based authentication (Negotiate) you will need either MS Internet
 158 Explorer 5.0+ running on Win2000 SP2 (or later) or Mozilla with the
 159 Negotiateauth extension (available in 1.7beta and later).
 160
 161 Internet Explorer
 162 -----------------
 163 To make the Negotiate authentication work the web server hostname  must be
 164 in Internet Explorer "Local Intranet" security zone and the "Windows
 165 Integrated Authentication" must be enabled in the IE advanced options.
 166
 167 See also a guide from Microsoft describing how to configure Windows Machine to
 168 use Unix KDC available at
 169 http://www.microsoft.com/windows2000/techinfo/planning/security/kerbsteps.asp
 170
 171 Mozilla
 172 -------
 173 First make sure your Mozilla distribution contains the Negotiateauth component
 174 (libnegotiateauth.so on Unix, negotiateauth.dll on Windows). Generally this is
 175 included in versions 1.7beta and later on Unix platforms including Mac OSX,
 176 maybe 1.8 and later on Windows.)
 177
 178 Next, you have to specify URL's for which it is allowed to use the Negotiate
 179 authentication method. It's done by setting the
 180 network.negotiate-auth.trusted-uris preference. In order to set it, just type
 181 "about:config" in the URL bar and then set the value of
 182 "network.negotiate-auth.trusted-uris" to "https://secured.webserver.name".
 183
 184 If you want to find out what happens in the Negotiateauth component use
 185 following environment variables:
 186   NSPR_LOG_MODULES=negotiateauth:5
 187   NSPR_LOG_FILE=/tmp/negotiateauth.log
 188 before starting Mozilla. You will see debugging messages logged in the file
 189 specified by NSPR_LOG_FILE (/tmp/negotiateauth.log)
 190
 191 KDE Konqueror
 192 -------------
 193 http://www.grolmsnet.de/kerbtut/konqueror.html
 194
 195 6. Access control
 196 -----------------
 197 If you want only particular users to be able to access the secured area, you
 198 can list their principal names in the appropriate Require directive. They must
 199 be full Kerberos names, including the REALM part. For example:
 200   Require user kouril@REALM.COM
 201
 202 The user's name is put by Apache in the REMOTE_USER environment variable so
 203 that it could be used by cgi-bin scripts.
 204
 205 $Id$