                     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"

     You may want to add these only inside a VirtualHost block that
     requires SSL to ensure that they are only accessible over SSL.

 5.  Set up a <VirtualHost> directive using SSL for the WebKDC service.
     Inside that directive, set a handler for the URL /webkdc-service.  In
     other words, use a configuration block like:

         <VirtualHost _default_:443>
            SSLEngine on
            ...
            <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:

         $KEYRING_PATH = "../conf/webkdc/keyring";
         $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.  There are
     other settings you can change; see doc/weblogin-config for all the
     details.

 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.)

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, do:

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

     uncomment the first line, and change the ACL pattern to match your
     realm.  This will allow any server with a webauth/* keytab to get an
     id token (which identifies a user but conveys no other privileges).
     This is a good place to start.  See the mod_webkdc manual for more.

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.

If you want to use let clients use SPNEGO to authenticate to the Weblogin
front-end with fallback to standard password authentication, see the
separate install-spengo documentation.
