X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=INSTALL;h=6cf767fe0bd17771c3990ba138afaedd6200a860;hb=dd2f3eb1e6e517dccaf6f5d9ebd963aceeaafe2c;hp=b42a17ac4640e9a2bfe5e480e44d0eef3f365928;hpb=ffe5f5598f53ac2d9a58e21a6e22a19ce26beaf9;p=mod_auth_kerb.git diff --git a/INSTALL b/INSTALL index b42a17a..6cf767f 100644 --- a/INSTALL +++ b/INSTALL @@ -1,182 +1,195 @@ -Basic Installation -================== - - These are generic installation instructions. - - The `configure' shell script attempts to guess correct values for -various system-dependent variables used during compilation. It uses -those values to create a `Makefile' in each directory of the package. -It may also create one or more `.h' files containing system-dependent -definitions. Finally, it creates a shell script `config.status' that -you can run in the future to recreate the current configuration, a file -`config.cache' that saves the results of its tests to speed up -reconfiguring, and a file `config.log' containing compiler output -(useful mainly for debugging `configure'). - - If you need to do unusual things to compile the package, please try -to figure out how `configure' could check whether to do them, and mail -diffs or instructions to the address given in the `README' so they can -be considered for the next release. If at some point `config.cache' -contains results you don't want to keep, you may remove or edit it. - - The file `configure.in' is used to create `configure' by a program -called `autoconf'. You only need `configure.in' if you want to change -it or regenerate `configure' using a newer version of `autoconf'. - -The simplest way to compile this package is: - - 1. `cd' to the directory containing the package's source code and type - `./configure' to configure the package for your system. If you're - using `csh' on an old version of System V, you might need to type - `sh ./configure' instead to prevent `csh' from trying to execute - `configure' itself. - - Running `configure' takes awhile. While running, it prints some - messages telling which features it is checking for. - - 2. Type `make' to compile the package. - - 3. Optionally, type `make check' to run any self-tests that come with - the package. - - 4. Type `make install' to install the programs and any data files and - documentation. - - 5. You can remove the program binaries and object files from the - source code directory by typing `make clean'. To also remove the - files that `configure' created (so you can compile the package for - a different kind of computer), type `make distclean'. There is - also a `make maintainer-clean' target, but that is intended mainly - for the package's developers. If you use it, you may have to get - all sorts of other programs in order to regenerate files that came - with the distribution. - -Compilers and Options -===================== - - Some systems require unusual options for compilation or linking that -the `configure' script does not know about. You can give `configure' -initial values for variables by setting them in the environment. Using -a Bourne-compatible shell, you can do that on the command line like -this: - CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure - -Or on systems that have the `env' program, you can do it like this: - env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure - -Compiling For Multiple Architectures -==================================== - - You can compile the package for more than one kind of computer at the -same time, by placing the object files for each architecture in their -own directory. To do this, you must use a version of `make' that -supports the `VPATH' variable, such as GNU `make'. `cd' to the -directory where you want the object files and executables to go and run -the `configure' script. `configure' automatically checks for the -source code in the directory that `configure' is in and in `..'. - - If you have to use a `make' that does not supports the `VPATH' -variable, you have to compile the package for one architecture at a time -in the source code directory. After you have installed the package for -one architecture, use `make distclean' before reconfiguring for another -architecture. - -Installation Names -================== - - By default, `make install' will install the package's files in -`/usr/local/bin', `/usr/local/man', etc. You can specify an -installation prefix other than `/usr/local' by giving `configure' the -option `--prefix=PATH'. - - You can specify separate installation prefixes for -architecture-specific files and architecture-independent files. If you -give `configure' the option `--exec-prefix=PATH', the package will use -PATH as the prefix for installing programs and libraries. -Documentation and other data files will still use the regular prefix. - - In addition, if you use an unusual directory layout you can give -options like `--bindir=PATH' to specify different values for particular -kinds of files. Run `configure --help' for a list of the directories -you can set and what kinds of files go in them. - - If the package supports it, you can cause programs to be installed -with an extra prefix or suffix on their names by giving `configure' the -option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. - -Optional Features -================= - - Some packages pay attention to `--enable-FEATURE' options to -`configure', where FEATURE indicates an optional part of the package. -They may also pay attention to `--with-PACKAGE' options, where PACKAGE -is something like `gnu-as' or `x' (for the X Window System). The -`README' should mention any `--enable-' and `--with-' options that the -package recognizes. - - For packages that use the X Window System, `configure' can usually -find the X include and library files automatically, but if it doesn't, -you can use the `configure' options `--x-includes=DIR' and -`--x-libraries=DIR' to specify their locations. - -Specifying the System Type -========================== - - There may be some features `configure' can not figure out -automatically, but needs to determine by the type of host the package -will run on. Usually `configure' can figure that out, but if it prints -a message saying it can not guess the host type, give it the -`--host=TYPE' option. TYPE can either be a short name for the system -type, such as `sun4', or a canonical name with three fields: - CPU-COMPANY-SYSTEM - -See the file `config.sub' for the possible values of each field. If -`config.sub' isn't included in this package, then this package doesn't -need to know the host type. - - If you are building compiler tools for cross-compiling, you can also -use the `--target=TYPE' option to select the type of system they will -produce code for and the `--build=TYPE' option to select the type of -system on which you are compiling the package. - -Sharing Defaults -================ - - If you want to set default values for `configure' scripts to share, -you can create a site shell script called `config.site' that gives -default values for variables like `CC', `cache_file', and `prefix'. -`configure' looks for `PREFIX/share/config.site' if it exists, then -`PREFIX/etc/config.site' if it exists. Or, you can set the -`CONFIG_SITE' environment variable to the location of the site script. -A warning: not all `configure' scripts look for a site script. - -Operation Controls -================== - - `configure' recognizes the following options to control how it -operates. - -`--cache-file=FILE' - Use and save the results of the tests in FILE instead of - `./config.cache'. Set FILE to `/dev/null' to disable caching, for - debugging `configure'. - -`--help' - Print a summary of the options to `configure', and exit. - -`--quiet' -`--silent' -`-q' - Do not print messages saying which checks are being made. To - suppress all normal output, redirect it to `/dev/null' (any error - messages will still be shown). - -`--srcdir=DIR' - Look for the package's source code in directory DIR. Usually - `configure' can determine that directory automatically. - -`--version' - Print the version of Autoconf used to generate the `configure' - script, and exit. - -`configure' also accepts some other, not widely useful, options. +1. Prerequisites +---------------- + - Development enviroment for Kerberos5 and/or Kerberos4 (i.e. libraries and + header files). The module works with the MIT Kerberos implementation + (supporting both krb4 and krb5), the kth-krb Kerberos4 implementation, + and the Heimdal Kerberos5 implementation. Kerberos libraries come with + most Linux distributions but they may not be installed by default. + - Apache server installed with SSL support. + Both 1.x and 2.x series of Apache are supported, provided they are + compiled to support DSO. SSL support (provided by either mod_ssl or + apache-ssl) is necessary for the module to work in a secure way. Most + Linux distributions contain suitable Apache packages. + - The latest source of the module available from the main project site + (http://sourceforge.net/project/showfiles.php?group_id=51775). + - Working C compiler, GNU make. + +2. Building and installing the module +------------------------------------- +Unpack the distribution tarball and run the configure script to set up the +build enviroment. The script will try to find krb5 and/or krb4 libraries and +headers and an Apache installation directory. You can use following flags to +specify locations of these files: + + --with-krb4= + --with-krb5= + these options are used to specify locations of the installation + directories for krb4 and krb5, respectively. If you don't want to + compile support for one of the method, use no as the appropriate + parameter or specify --without-krb5 or --without-krb4. + --with-apache= + use this parameter to specify location where the Apache installation + resides. + +After the configuration script finishes run make followed by make install. +In order to install the module you will have to have writing permission for +the apache directory. + +An example of the building stage follows: + ./configure --with-krb5=/software/krb5-1.3.1 \ + --with-krb4=no \ + --with-apache=/software/apache-2.0.47 + make + su + make install + +3. Create the Kerberos principal for the server +----------------------------------------------- +A service principal for the web server must be registered with the KDC in +order to let the module verify users properly. In general the principals for +web servers have names with format HTTP/servername@REALM, where servername +is the fully-qualified domain name of the server and REALM is your Kerberos +realm. If you have multiple virtual servers requiring authentication +service principals have to be generated for each virtual servername. After +creating the service principal, corresponding Kerberos keys must be +extracted to a keytab file stored on the server host. Steps to create the +principal and extracting the keys vary depending on the KDC server type +used. + +Heimdal or MIT KDC +------------------ +From the www machine start the kadmin command, connect to the KDC and create +principal HTTP/servername@REALM with a random key(s). Then extract the keys +into a local keytab and change ownership and permissions for the keytab +file so that only the apache user can access it. Example using kadmin from +Heimdal: + kadmin -p admin@REALM -r REALM ank -r HTTP/servername@REALM + kadmin -p admin@REALM -r REALM ext -k /etc/httpd/keytab HTTP/servername@REALM + chown nobody /etc/httpd/keytab + chmod 400 /etc/httpd/keytab + +Windows 2000 Domain Controler +----------------------------- +The Kerberos realm in Active Directory is the same as the DNS domain +name of the AD domain. For example, a Kerberos principal for host +server.example.com might be "HTTP/server.example.com@EXAMPLE.COM". + +To install the principal in AD you first need to create a user account in the +domain for the server. It makes sense to call this account something +meaningful, maybe "httpd_servername" so that it is obvious what this account is +used for. To create the account you can use standard AD tools. Make sure that +the user account has "Password never expires" set and write down the password +you set for the account (you will need it later). + +When using ticket based authentication (KrbMethodNegotiate) and also wanting +to save the ticket (KrbSaveCredentials), the user account for the Kerberos +principal must have the option "Account is trusted for delegation" set. This +enables to user account to delegate the tickets to the server for further +authentication. + +If you want to kerberize additional hosts you need to create one user account +per each kerberized host. + +The Kerberos principal is associated with a user account with the ktpass.exe +tool that is part of the Microsoft Support Tools package. This tools needs to +be run on a domain controller. To associate a Kerberos principal with a user +account just run ktpass.exe in a command prompt with appropriate parameters to +create a keytab file. Full description of the ktpass.exe command can be found +at http://support.microsoft.com/default.aspx?scid=kb;en-us;324144. + +ktpass -out c:\apache.ktab -princ HTTP/server.name@REALM.NAME + -pass account_password -mapuser httpd_servername -crypto DES-CBC-MD5 + +In the above the c:\apache.ktab is the name of the created keytab file, +account_passwored is the password you set for the user account and +httpd_servername is the name of the user account. The DES-CBC-MD5 encryption +is needed to get Heimdal to work with Microsoft KDC, MIT Kerberos does not +seem to need it but it does not hurt either. In fact, RFC1510 discourages +using DES-CBC-CRC (default in Win2k ktpass.exe) so it's probably better to +use DES-CBC-MD5 in all cases. + +You need to copy the keytab file to your web server in a secure way to avoid +revealing the server key(s). Note that the copy needs to be done in binary +mode to avoid corrupting the file. Make sure that the keytab file is owned by +the apache user and only readable to this user (i.e. the permissions are 400). +After copying the keytab verify the content using the ktutil tool. + +See http://www.grolmsnet.de/kerbtut for more information about using +mod_auth_kerb with Windows KDC. + +4. Verifying krb5 on the server host +------------------------------------ +Before starting configuring the module make sure your Kerberos enviroment on +the web host is properly configured. The easiest way to check is using the +kinit command to get a ticket from the KDC. + +5. Configuring mod_auth_kerb +---------------------------- +First make sure that Apache works as expected. + +You need to load the mod_auth_kerb module. To do this, add a LoadModule +statement into the appropriate section of httpd.conf file. + +LoadModule auth_kerb_module modules/mod_auth_kerb.so + +The configuration of mod_auth_kerb can be done per directory. The +configuration directives can be stored in either a section of +httpd.conf or in a .htaccess file in the coresponding directory. Example of a +Directory section from httpd.conf: + + + AuthType Kerberos + AuthName "Kerberos Login" + Krb5Keytab /etc/apache/apache.keytab + KrbAuthRealms EXAMPLE.COM + Require valid-user + + +The Krb5Keytab file is the one created as described above in section 3. + +Summary of all configuration directives supported by the module can be found in +README. + +6. Configuring the browsers +--------------------------- +For password based authentication any browser supporting the Basic HTTP +authentication method can be used without any changes. In order to use +ticket based authentication (Negotiate) you will need either MS Internet +Explorer 5.0+ running on Win2000 SP2 (or later) or Mozilla with the +Negotiateauth extension (available in 1.7beta and later). + +Internet Explorer +----------------- +To make the Negotiate authentication work the web server hostname must be +in Internet Explorer "Local Intranet" security zone and the "Windows +Integrated Authentication" must be enabled in the IE advanced options. + +See also a guide from Microsoft describing how to configure Windows Machine to +use Unix KDC available at +http://www.microsoft.com/windows2000/techinfo/planning/security/kerbsteps.asp + +Mozilla +------- +First make sure your Mozilla distribution contains the Negotiateauth component +(libnegotiateauth.so on Unix, negotiateauth.dll on Windows). Generally this is +included in versions 1.7beta and later on Unix platforms including Mac OSX, +maybe 1.8 and later on Windows.) + +If you want to find out what happens in the Negotiateauth component use +following environment variables: + NSPR_LOG_MODULES=negotiateauth:5 + NSPR_LOG_FILE=/tmp/negotiateauth.log +before starting Mozilla. You will see debugging messages logged in the file +specified by NSPR_LOG_FILE (/tmp/negotiateauth.log) + +6. Access control +----------------- +If you want only particular users to be able to access the secured area, you +can list their principal names in the appropriate Require directive. They must +be full Kerberos names, including the REALM part. For example: + Require kouril@REALM.COM kouril REALM.CZ + +The user's name is put by Apache in the REMOTE_USER environment variable so +that it could be used by cgi-bin scripts. + +$Id$