                     WebKDC Installation Instructions

These are supplemental installation instructions for installing a WebKDC.
Each site running WebAuth only needs one WebKDC for the entire site, so
normally users do not need to follow these steps.  They are here only for
site WebAuth administrators.

It is important to always keep in mind that the security of the entire
WebAuth system depends on the security of the WebKDC.  A compromise of the
WebKDC system would allow an attacker to steal usernames and passwords for
anyone using the login server and to be able to forge arbitrary
authentication credentials and use them to contact WebAuth servers.  This
system should be locked down as tightly as possible and proactively
monitored for security.

 1.  Follow the standard WebAuth installation instructions as given in the
     INSTALL file at the top of the source tree, but also pass the flags
     --enable-mod_webkdc, --disable-mod_webauth, and 
     --disable-mod_webauthldap to ./configure.  This will install the WebKDC
     module as well as the basic WebAuth module, and it will also install
     the Perl bindings (into the site_perl directory for the first version
     of Perl found on your path).

 2.  You'll need to install the following Perl modules from CPAN:

         HTML::Template
         FCGI
         Crypt::SSLeay (for LWP https support)

     You'll probably also want to install and configure mod_fastcgi as
     well, though it's not a requirement.  If you decide to install it,
     you'll need to configure it like so:

         FastCGIConfig -initial-env LD_LIBRARY_PATH
         LoadModule fastcgi_module modules/mod_fastcgi.so
         <Directory "webkdc">
             AllowOverride All
             Options Indexes FollowSymlinks +ExecCGI
             AddHandler fastcgi-script .fcgi
             Order allow,deny
             Allow from all
         </Directory>

 3.  Add Apache directives for the WebKDC.  The basic set is:

         LoadModule webkdc_module modules/mod_webkdc.so
         WebKdcServiceTokenLifetime 30d
         WebKdcKeyring conf/webkdc/keyring
         WebKdcKeytab conf/webkdc/keytab
         WebKdcTokenAcl conf/webkdc/token.acl

     If you are testing a beta release, please also add:

         WebKdcDebug on

     so that your server will generate more complete logs if anything goes
     wrong.  This may also be useful if this is the first time you've
     installed a WebKdc.  You'll also want to set LogLevel to debug:

         LogLevel debug
     
 4.  Set up a script aliases to run the login CGI service by adding the
     following lines to your Apache configuration:

         ScriptAlias /login "webkdc/login.fcgi"
         ScriptAlias /logout "webkdc/logout.fcgi"
         Alias /images "webkdc/images/"
         Alias /help.html "webkdc/help.html"

 5.  Set up a <VirtualHost> directive using SSL for the WebKDC service ,
     running on some port other than the standard port (since the login
     server will run on the standard port).  Inside that directive, set a
     handler for the URL /webkdc-service.  In other words, use a
     configuration block like:

         <VirtualHost _default_:8443>
         ...
         <Location /webkdc-service>
            SetHandler webkdc
         </Location>
         ...
         </VirtualHost>

 6.  Create the conf/webkdc directory and the webkdc directory:

         cd <apache-root>
         mkdir -p conf/webkdc webkdc

 7.  Install the WebKDC files used by the login server, the portion that
     runs on the regular SSL port.  cd to the root of the WebAuth source
     tree and then run:

         make install-webkdc

 8.  If the path and URL in <apache-root>/webkdc/WebKDC/Config.pm are not
     correct for your site, create /etc/webkdc/webkdc.conf and in it put
     lines like:

         our $KEYRING_PATH = "../conf/webkdc/keyring";
         our $URL = "https://localhost/webkdc-service/";

     changing the values to what is appropriate for your site.  If you
     follow the default recommendations on where to place the keyring
     and CGI scripts, you shouldn't have to change anything.

 9.  Install a keytab for the WebKDC.  This keytab must be for the same
     identity as is mentioned in the WebAuthWebKdcPrincipal configuration
     option in the Apache configuration of individual WebAuth servers.
     The keytab should for the identity service/webkdc, and should be
     installed in <apache-root>/conf/webkdc/keytab.

     (Note that you can use some other identity if you prefer, as this is
     part of the WebAuth module configuration.  You'll just then have to
     configure all of your systems using the WebAuth module to use
     whatever other identity you chose.)

     At Stanford, this can be done with:

         /usr/pubsw/sbin/leland_srvtab \
             -f <apache-root>/conf/webkdc/srvtab \
             -k <apache-root>/conf/webkdc/keytab \
             service.webkdc

     and then deleting the srvtab file (since it's not needed).

10.  Create a file named token.acl in <apache-root>/conf/webkdc.  This
     file specifies which tokens various server identities are allowed to
     create.  There is an example file in src/modules/webkdc/token.acl, so
     for an initial configuration at Stanford, just do:

         cp src/modules/webkdc/token.acl <apache-root>/conf/webkdc/

     At other sites, you'll need to at least change the ACL pattern to not
     use @stanford.edu.

11.  Restart the Apache web server.  You should now have a working WebKDC
     and login server, which you can point a WebAuth server at.  You will
     need to install a regular WebAuth server following the instructions
     in INSTALL to be able to test your WebKDC.
