Apache Module mod_webkdc

Setting up the WebKDC

The minimal configuration for the WebKDC requires two things: a keytab for the Kerberos principal used by the WebKDC to authenticate requests from application servers, and the token.acl file that specifies what tokens application servers are permitted to request.

The keytab must be a Kerberos V5 keytab for the principal referenced in the WebAuthWebKdcPrincipal configuration directive on the application servers. How to obtain a keytab will depend on one's local Kerberos infrastructure; it may be via kadmin or via some other local interface.

For information about the token.acl file, see the WebKdcTokenAcl documentation below.

Finally, the one piece of state that the WebKDC must maintain is its local keyring, which holds the AES keys that it uses to encrypt and decrypt tokens. This keyring can either be generated and updated automatically (the default) or managed externally using wa_keyring. See WebKdcKeyringAutoUpdate for more information.

The WebKDC must get a URL to itself on the host where it is running. By convention, /webkdc-service is used. This URL must be only accessible via SSL, for security reasons.

Minimal Config File

The following example shows the minimum config file required to configure and use mod_webkdc.

LoadModule webkdc_module modules/mod_webkdc.so

WebKdcServiceTokenLifetime 30d
WebKdcKeyring conf/webkdc/keyring
WebKdcKeytab conf/webkdc/keytab
WebKdcTokenAcl conf/webkdc/token.acl

<VirtualHost _default_:443>
  <Location /webkdc-service>
     SetHandler webkdc
  </Location>
</VirtualHost>

WebKDC Logging

All commands received by the WebKDC and their results are logged to the Apache error log with a log level of "notice". These log messages always begin with the string "mod_webkdc: event=" followed by the event, which is one of the following:

getTokens

A request for a service, id, proxy, or cred token. You will see this action most frequently from WebAuth web servers acquiring new service tokens for use later when redirecting users to the WebLogin server and decoding the response. When delegating user credentials to WebAuth application servers, those servers will send a getTokens request to the WebKDC to obtain those delegated credentials.

requestToken

A request for an id or proxy token for a user. A proxy token for the WebKDC itself will also be returned for use with future requests by the same user. This call will normally only be done by the WebLogin component of the WebKDC service; while the call is available to any client, clients wishing to bootstrap WebAuth cookies on their own should use the much simpler webkdcProxyToken call instead.

webkdcProxyToken

A request for a WebKDC proxy token (the token contained in the WebAuth single sign-on cookie) given a Kerberos authenticator. This can be used by clients to bootstrap a WebAuth single sign-on cookie without having to visit the WebLogin server in a browser.

webkdcProxyTokenInfo

Given a WebKDC proxy token, returns various metadata about it, such as its expiration time.

Those who are familiar with the WebAuth protocol will recognize that the four events logged are the four XML elements that the WebKDC protocol permits. (Other errors, such as unknown commands, are of course also logged.)

Following the event will be additional key/value pairs in the form key=value. The possible keys are:

clientIp

Only for requestToken requests, this contains the client IP address as indicated by the WebLogin server. If the WebLogin server didn't include the client IP address in the request, the value will be empty. Please note that the WebKDC does not authenticate this information, only records whatever was passed in by the WebLogin server, which means that if from is not 127.0.0.1 (meaning that the requestToken request didn't come from the WebLogin server), the value of this key should not be trusted.

errorCode

The error code for a protocol-level error. The presence of this key means that some failure occurred in the course of parsing the XML document and therefore no action was taken in the WebKDC.

errorMessage

The error message corresponding to the error code from a errorCode key.

from

The IP address from which the request came. For requestToken in the recommended configuration of running WebLogin servers on the same host as the WebKDC, this will normally always be 127.0.0.1, but will be more interesting for the other events.

lec

The login error code, only included for requestToken. If this is 0, the call was successful. Otherwise, it contains the error code.

lem

If lec is non-zero in requestToken, this contains the error message corresponding to that error code.

ro

Any request options set by the WebAuth server. The most common value here is "fa", indicating that the WebAuth server requested forced password authentication even if the user already had single sign-on credentials. For more details on the possible values, see the WebAuth protocol specification.

rtt

The returned token type from a requestToken request. Normally this will be "id" for an id token, but may be another token type depending on what the WebAuth server asked for.

server

For getTokens and requestToken, this will contain the identifier of the requesting server (in the case of requestToken, this is the server that sent the user to WebLogin).

type

The type of token acquired by a getTokens call.

user

The user being authenticated. This will normally be the username portion of a Kerberos identity, if it is known, for requestToken. For protocol-level errors, it often will be unknown (because the protocol failed before the username was established) and will instead be the string "<unknown>". For getTokens, it will be the user the tokens are for (the same as server in the most common case of acquiring service tokens).

Setting up Multiple WebKDCs

WebAuth V3 was designed so that it would be fairly easy to setup multiple WebKDCs for load balancing and redundancy. There are three pieces of information that need to be shared between WebKDC servers in order to achieve this:

1. Token ACL file
2. Kerberos keytab file
3. WebKDC keyring file

By convention, one of the WebKDC's should be designated as the "master" and other WebKDC's should be designated as "slaves." These files should only be updated on the master and pushed manually or automatically to the slaves.

The token ACL file is specified using the WebKdcTokenAcl directive. This file should be maintained on the "master" WebKDC, and copied to other WebKDCs.

The Kerberos keytab file is specified using the WebKdcKeytab directive. This is a standard Kerberos V5 keytab file containing the principal used by WebAuth servers to initially communicate with the WebKDC. This is a binary file that should be kept consistent across all the WebKDC servers. Normally this means that you will need to download it once and then copy it between systems, since Kerberos V5 generally changes the key of a principal when downloading a new keytab for it.

The WebKDC keyring file is specified using the WebKdcKeyring directive. This file contains the WebKDCs private AES keys. If you are running multiple WebKDCs, you must turn off automatic updating of the WebKDCs keyring file on restarts. This is done using the WebKdcKeyringAutoUpdate directive:

Once auto update is turned off, the keyring file will not be automatically updated, and can be manually updated and then copied between the servers. The keys in the keyring file still need to be changed periodically using the wa_keyring command. This command would be run on the keyring file on the master, and then the new keyring should be copied to the slaves. For example, to generate a new post-dated key in the file called "keyring" you should do the following:

That example generates a new key that will be valid in seven days. Any existing keys in the keyring file are left as-is so outstanding tokens continue to work. The new keyring file can then safely be distributed to the slave WebKDCs. Then, the WebKDC must be restarted to pick up the new key.

Old keys in the keyring file should also periodically be removed. This should be done using wa_keyring and the gc command:

wa_keyring -f ./keyring gc -60d

This command would remove any key older than 90 days. The time interval that you pass to the gc command must be older than the service token lifetime as specified with WebKdcServiceTokenLifetime. The recommendation is to make it about twice as long.

To summarize, for each WebKDC (master and slaves), you'd want the following directives:

LoadModule webkdc_module modules/mod_webkdc.so

WebKdcServiceTokenLifetime 30d
WebKdcKeyring conf/webkdc/keyring
WebKdcKeytab conf/webkdc/keytab
WebKdcTokenAcl conf/webkdc/token.acl
WebKdcKeyringAutoUpdate off

<VirtualHost _default_:443>
  <Location /webkdc-service>
     SetHandler webkdc
  </Location>
</VirtualHost>

Periodically (once a month should be reasonable), you'd want to generate a new key, remove old keys, and then update the keyring file on the slaves using a script like this:

wa_keyring -f conf/webkdc/keyring add 2d
wa_keyring -f conf/webkdc/keyring gc -60d
apache2ctl graceful
for host in slave1 slave2 ; do
    scp conf/webkdc/keyring $host:/path/to/conf/webkdc/keyring
    ssh $host apache2ctl graceful
done

If the servers are restarted regularly (such as for nightly log rotation), you can omit the apache2ctl graceful restart and just let that restart pick up the new keys. The reason for post-dating the key is to make sure that all of the servers pick it up before it becomes valid and is used in service tokens.