WebAuth WebKDC for Debian
-------------------------

This package contains the Apache module for the central WebAuth WebKDC.
Only one server (or one pool of load-balanced servers) at a given site
need to run this module.  On the server that you install this module, you
should also install the webauth-weblogin package and follow its
installation instructions.  The documentation for it has additional
information about what site configuration documentation you will probably
want to publish for WebAuth users at your site.

mod_webkdc.html.en is the formatted manuals, but it expects to be part of
the Apache documentation tree.  If you wish, you can install the
apache2-doc package and then copy this file into:

    /usr/share/doc/apache2-doc/manual/mod/

and you will then be able to read it as intended.

See:

    <http://webauth.stanford.edu/>

for more information about WebAuth, including copies of the module manuals
and places to contact to get help with the installation.


Installing the WebKDC
---------------------

After installing this package, you must also do the following to make the
WebKDC available:

 1. Decide what the URL will be for your WebKDC service.  I recommend
    <https://weblogin.example.com/webkdc-service/>, where example.com is
    your domain, but you can use anything that you wish.  It should,
    however, be on the same server as the weblogin server.

 2. Decide what Kerberos principal to use for the WebKDC service.  I
    recommend service/webkdc (in your local realm), but you can use
    anything that you wish.

 3. Obtain a Kerberos keytab for the WebKDC.  How to obtain a keytab
    varies greatly from one Kerberos site to the next; contact your local
    Kerberos administrator for more information.

    However you get this keytab, install it in /etc/webkdc/keytab and
    then make sure that it is readable by the web server:

        chgrp www-data /etc/webkdc/keytab
        chmod 640 /etc/webkdc/keytab

 4. In the configuration for your SSL virtual host, or your main server
    configuration if you don't configure SSL separately, add a block like:

        <Location /webkdc-service>
            SSLRequireSSL
            SetHandler webkdc
        </Location>

    You will also have to have a working SSL configuration, which includes
    a valid SSL certificate that your WebAuth servers will be able to
    validate.  See the Apache documentation for information on setting up
    SSL.

 5. Edit /etc/webkdc/token.acl and configure which Kerberos principals
    will be allowed to get tokens from the WebKDC.  I recommend starting
    with a line like:

        krb5:webauth/*@EXAMPLE.COM id

    which will allow any webauth/* principal in the EXAMPLE.COM realm
    (replace that with your own realm) to get an "id" token, which is the
    token for basic authentication.  You can allow particular servers to
    get additional Kerberos credentials on behalf of the user; for more
    information, see the manual.

 6. Enable the WebKDC module:

        a2enmod webkdc

    The WebKDC module will now be loaded the next time you restart your
    Apache server.

 9. Restart Apache:

        apache2ctl graceful

    The WebKDC should now be available, and you can start testing with
    WebAuth servers.

 -- Russ Allbery <rra@debian.org>, Mon, 22 Apr 2013 13:47:30 -0700
