mod_webkdc
WebAuth WebKDC module
External
mod_webkdc.c
webkdc_module
Apache 2.0 and higher

This module implements the central authentication server for the WebAuth protocol, also known as the WebKDC.

The WebKDC authenticates the user based on information passed by the WebLogin service (which should generally run on the same system) and generates authentication tokens both for the user's cookie cache to support single sign-on and to send to application servers to authenticate the user. It is designed to store as little state as possible, using the browser cookie cache as the repository for (encrypted) authentication tokens and ticket caches.

Further details are provided in the WebAuth documentation.

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

## Example

    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. Values containing whitespace or double quotes will be enclosed in double quotes. Any double quotes in the value will be doubled; in other words, the character " in the value will be represented as "" inside a double-quoted string. The possible keys are:

authz

  Only for `requestToken` requests, this indicates that the user is asserting an authorization identity to this WAS. The value of this key will be the authorization identity that was asserted. The authorization identity was validated against the identity ACL file. See WebKdcIdentityAcl for more information.

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.

ifactors

  The initial authentication factors of this successful authentication.

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.

loa

  The Level of Assurance of this successful authentication.

login

  If this request represents an initial user login (as opposed to an authentication using single sign-on credentials), this key is present and the value will indicate the type of authentication (password or otp, or both if both are provided at the same time.

pt

  For tokens of type `proxy`, this will contain the proxy token type. Currently, the only supported proxy token type is `krb5`, which can be used by the WebAuth Application Server to request Kerberos credentials on behalf of the user from the WebKDC.

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.

sa

  The requested subject authenticator type for a `requestToken` operation. If the WebAuth Application Server requests an id token, this will indicate the type of id token it is requesting. Possible values are `webkdc`, which provides the user's identity but no additional information, or `krb5`, which provides a Kerberos authenticator for the user that can be verified by the WebAuth Application Server's Kerberos key.

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

sfactors

  The session authentication factors of this successful authentication.

type

  The type of token acquired by a `getTokens` call.

url

  For `requestToken`, this will contain the return URL to which the browser will be sent after authentication.

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

wifactors

  The initial authentication factors required by the WebAuth Application Server.

wloa

  The Level of Assurance required by the WebAuth Application Server.

wsfactors

  The session authentication factors required by the WebAuth Application Server.

# Setting up Multiple WebKDCs

WebAuth 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

## Note

All the files should be securely transferred from the master to the slave or slaves using a program like `scp` that encrypts the file contents during the transfer.

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

## Turning off auto update

WebKdcKeyringAutoUpdate off

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:

## Generating a post-dated key

wa_keyring -f ./keyring add 2d

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:

## Automatically removing old keys

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:

## Example

    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, but there's no drawback to doing it daily so that you'll more quickly notice problems in the process), 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:

## Monthly Key maintenance

    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.

# Manual License

Copyright 2002, 2003, 2005, 2006, 2008, 2009, 2011, 2012, 2014 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

WebKdcDebug
Turn on extra debugging in the Apache error log
WebKdcDebug on|off
WebKdcDebug off
server config
virtual host

Whether or not to log additional debugging messages to the Apache server log.

# Example

WebKdcDebug on
WebKdcFastArmorCache
Path to crednetial cache for FAST armor tickets
WebKdcFastArmorCache path
(none)
server config
virtual host

FAST (Flexible Authentication Secure Tunneling) is a way of protecting the initial Kerberos AS-REQ exchange for a password authentication with armor based on stronger keys, such as randomly-generated keys in a keytab. This directive specifies a Kerberos ticket cache to use with FAST to protect any password authentications done by the KDC.

The path argument must point to an existing Kerberos ticket cache, not a keytab or other source of Kerberos keys. To maintain a Kerberos ticket cache from a keytab, use a program such as k5start. The path argument can be a path to a ticket cache on disk, or any other Kerberos ticket cache specification that can be read by the Apache server.

If this directive is set, FAST will be used and required for all password authentications, and if FAST setup fails, the authentication will fail. If this directive is set and the Kerberos KDC does not support FAST, all password authentications will fail.

# Example

WebKdcFastArmorCache /var/run/webkdc/krb5cc_armor
WebKdcIdentityAcl
Path to the ACL file for authorization identities
WebKdcIdentityAcl path
(none)
server config
virtual host

This directive, if set, points to an ACL file that controls whether a user can assert an authorization identity to a particular WebAuth Application Server that is different than their authenticated identity. By default, it is not set, which disables all authorization identity support in the WebKDC.

An authorization identity is an alternate identity, different than the identity as which the user authenticated, that should be used for identification and access control in the WebAuth Application Server. When an authorization identity is provided, both it and the authentication identity are passed to the WAS, and the WAS can choose which to honor. By default, even if this directive is enabled on the WebKDC and the user asserts an authorization identity, that identity is ignored by the WAS. Support for authorization identities must also be explicitly enabled on the WAS.

Each line in the identity ACL file is a space-separated grant of permission for a particular user to assert a particular authorization identity to a particular site. Each line has three fields:

1. The authenticated identity of the user to which this permission is granted. This is the identity after any normalization or realm stripping and should match the identity that would be passed to the WebAuth Application Server, put in REMOTE_USER, and so forth.

2. The identity of the WAS to which that user can assert an authorization identity. This is an identity, not a URL, and is the same value that is matched against the token ACL file (see WebKdcTokenAcl). At present, just as with the token ACL file, it is always a Kerberos principal preceded by `krb5:`.

3. The authorization identity that the user is permitted to assert. This must be exactly the value that will be passed to the WebAuth Application Server.

No wildcards are supported. Multiple lines for the same user and same WAS are allowed, representing multiple different authorization identities that user is allowed to assert to that WAS. Blank lines and lines beginning with `#` are ignored.

# Example ACL File

    # Allow alice to assert an identity of bob to foo.example.org.
    alice krb5:webauth/foo.example.org@EXAMPLE.ORG bob

    # Allow alice to assert a cross-realm identity to foo.example.org.
    alice krb5:webauth/foo.example.org@EXAMPLE.ORG alice@EXAMPLE.COM

    # Allow joe to assert an identity of testuser on foo-test.example.org.
    joe krb5:webauth/foo-test.example.org@EXAMPLE.ORG testuser

If the path is not absolute, it will be considered relative to ServerRoot.

# Example

WebKdcIdentityAcl conf/webkdc/id.acl
WebKdcKerberosFactors
Initial factor information for directly-obtained webkdc-proxy tokens
WebKdcKerberosFactors factor ...
WebKdcKerberosFactors u
server config
virtual host

This directive sets the initial factor information for the webkdc-proxy tokens obtained by clients by direct Kerberos authentication (rather than by WebLogin). If left unset, the default factor will be set to 'unknown'.

# Example

WebKdcKerberosFactors p
WebKdcKeyring
Name of the file containing the WebKDC's keyring
WebKdcKeyring path
(none)
server config
virtual host

This is the name of the file containing the WebKDC's keyring, which stores the server's private AES keys. It must be readable by the Apache user.

The keyring file is read when the first request for a virtual host is received. Each child maintains an in-memory cached keyring for each virtual host. These keyrings are only reloaded from disk when Apache refreshes its configuration. If the keyring is changed by an external process (`wa_keyring`, for instance), Apache must be told to reload configuration files in order to pick up the change.

When using the ITK Apache MPM, there should be a separate keyring for each unique virtual host user that will be serving as a WebKDC. This maintains proper privilege separation by assigning each user a separate keyring.

If the path is not absolute, it will considered relative to ServerRoot.

# Note

This directive must be set.

# Example

WebKdcKeyring conf/webkdc/keyring
WebKdcKeyringAutoUpdate
Whether or not to auto-update the keyring file
WebKdcKeyringAutoUpdate on|off
WebKdcKeyringAutoUpdate on
server config
virtual host

This directive controls whether or not we auto-update the keyring file. This includes creating it if it doesn't exist, generating a new key before the old key expires, and periodically garbage-collecting old keys. Updating only occurs on server startup and restarts.

If auto-update is enabled, Apache must have write access to the directory containing the keyring, since keyrings are updated by writing out the new file to a separate name and then atomically replacing the file.

Ownership (user and group) of the existing keyring file will be preserved if possible without overwriting the existing file. Permissions will also be preserved, with the exception that permissions will not be copied to the new file if the old file was group-readable or group-writable and setting the group ownership failed.

# Note

This directive should be turned off if multiple servers are sharing the same keyring file, so that the keyring file can be manually updated. That too may eventually be automated.

# Example

WebKdcKeyringAutoUpdate off
WebKdcKeyringKeyLifetime
Lifetime of keys in the keyring if we auto-update
WebKdcKeyringKeyLifetime nnnn[s|m|h|d|w]
WebKdcKeyringKeyLifetime 30d
server config
virtual host

This directive controls how long keys we automatically create for the keyring are valid. Keys will be valid from the time they are created until the lifetime is reached. It is equivalent to the time specified to `wa_keyring gc`, except that the latter expects a negative time. Note that key lifetime is only checked on server startup and restarts.

This directive is only consulted if WebKdcKeyringAutoUpdate is enabled.

The units for the time are specified by appending a single letter. This letter may be one of `s`, `m`, `h`, `d`, or `w`, which correspond to seconds, minutes, hours, days, and weeks, respectively.

# Example

WebKdcKeyringKeyLifetime 60d
WebKdcKeytab
Name of the Kerberos keytab file
WebKdcKeytab path [principal]
(none)
server config
virtual host

This is the name of the Kerberos keytab file, used by the WebKDC to authenticate initial requests from application servers. The principal is optional and can be used to specify a particular principal in a keytab file that contains several. If it is not specified, then the first principal in the keytab file be used.

If the path is not absolute, it will considered relative to ServerRoot.

# Note

This directive must be set.

# Example

WebKdcKeytab conf/webkdc/keytab service/webkdc
WebKdcLocalRealms
Realms to be stripped from authenticated identities
WebKdcLocalRealms none|local|realm ...
WebKdcLocalRealms local
server config
virtual host

This directive controls stripping realm qualifications from the authenticated identity of a WebAuth user. The realm is defined as the portion of the authenticated identity following the first unescaped `@` in the identity.

If set to `none`, no transformations are done and the authenticated identity is always passed in its fully-qualified form. This is probably the best option for sites that use multiple local Kerberos realms where none is the logical default realm.

If set to `local` (the default), the authenticated identity will be passed to the krb5_aname_to_localname function on the WebKDC. Normally, this will strip off the realm if it matches the default Kerberos realm of the WebKDC (not the requesting WebAuth Application Server) and otherwise leave it; however, more complex canonicalization rules may be specified in the `/etc/krb5.conf` file on the WebKDC.

Otherwise, the space-separated arguments to this directive are taken to be realms that should be stripped from the authenticated identity.

# Note

The canonicalization done is that specified on the WebKDC, not in the WebAuth Application Server. There is no way to perform different authenticated identity canonicalization on different WebAuth Application Servers using the same WebKDC.

# Example

    # Strip stanford.edu and WIN.STANFORD.EDU but leave other realms
    WebKdcLocalRealms stanford.edu WIN.STANFORD.EDU

WebKdcLoginTimeLimit
Time limit for completing login process and for considering a login to be recent
WebKdcLoginTimeLimit nnnn[s|m|h|d|w]
WebKdcLoginTimeLimit 5m
server config
virtual host

This directive controls how long a user is permitted to take to complete the login process, and, related, how long before a user's login is not considered to have "just happened."

In some cases, particularly when multifactor authentication is in use or the user is permitted to assert an authorization identity, the interaction with WebLogin can involve multiple independent steps. This directive sets a time limit within which each of those actions is considered to be part of the same session. If the user takes longer than this time limit to complete the login process, their first actions will expire and they are likely to have to begin again.

This is also the time limit within which the authentication factors presented by the user will be considered session factors as well as initial factors. This affects restrictions on session factors set by the WebAuth Application Server (using WebAuthRequireSessionFactor, for example). If the user has authenticated within this time limit, they will not be forced to reauthenticate, even when going to a different WebAuth Application Server than the one that prompted their original authentication.

The units for the time are specified by appending a single letter. This letter may be one of `s`, `m`, `h`, `d`, or `w`, which correspond to seconds, minutes, hours, days, and weeks, respectively.

This directive may be set to `0s` to disable this grace period entirely. This will mean that any session factor requirement in a required reauthentication, at the cost of making multistage multifactor authentication impossible. It will also prevent asserting an authorization identity while satisfying a session factor requirement impossible unless the user is prompted for an authorization identity at the time of login.

# Examples

    # The user must complete the login process in 90 seconds
    WebKdcLoginTimeLimit 90s

    # Disable the grace period entirely.
    WebKdcLoginTimeLimit 0s

WebKdcPermittedRealms
List of permitted authentication realms
WebKdcPermittedRealms realm ...
(none)
server config
virtual host

By default, the WebKDC allows authentication via any realm with which there is cross-realm trust. If this directive is given, it restricts authentication to principals in one of the realms listed in this directive.

# Example

WebKdcPermittedRealms stanford.edu WIN.STANFORD.EDU
WebKdcProxyTokenLifetime
Lifetime of webkdc-proxy tokens we create
WebKdcProxyTokenLifetime nnnn[s|m|h|d|w]
(lifetime of underlying proxied-credential)
server config
virtual host

This directive controls the lifetime of the webkdc-proxy token (the main single-sign-on cookie containing the user's proxied credentials). If not specified, the lifetime time used is the expiration time of the underlying credential (i.e., the lifetime of the Kerberos TGT for example).

Tokens created with a webkdc-proxy token (id, proxy, cred) will have the same expiration time as the webkdc-proxy token, so this directive also controls the lifetime of those tokens as well.

The units for the time are specified by appending a single letter. This letter may be one of `s`, `m`, `h`, `d`, or `w`, which correspond to seconds, minutes, hours, days, and weeks, respectively.

# Note

The upper bound of the webkdc-proxy token is always bounded by the expiration time of the underlying proxied credential. For example, if the Kerberos TGT expires in 25 hours, then the WebKDC will not create a webkdc-proxy token with a lifetime greater then 25 hours, even if this directive is set higher then 25 hours.

# Example

    # create a webkdc-proxy token valid for 2 hours
    WebKdcProxyTokenLifetime 2h

WebKdcServiceTokenLifetime
Lifetime of webkdc-service tokens we create
WebKdcServiceTokenLifetime nnnn[s|m|h|d|w]
(none)
server config
virtual host

This directive controls the lifetime of the webkdc-service token we create. This controls how often a WebAuth application server needs to re-authenticate with the WebKDC to get a new service token. The lifetime of the service token (and the webkdc-proxy-token) control how often the WebKDC can change its private key, and how long it should retain the previous key for.

A reasonable setting for this directive is 30 days, with the private key of the WebKDC being changed every 60 days or so, keeping the previous WebKDC private key around for 30 days after it expires.

The units for the time are specified by appending a single letter. This letter may be one of `s`, `m`, `h`, `d`, or `w`, which correspond to seconds, minutes, hours, days, and weeks, respectively.

# Note

This directive must be set.

# Example

    # create a webkdc-service token valid for 30 days
    WebKdcServiceTokenLifetime 30d

WebKdcTokenAcl
Path to file containing the token ACL
WebKdcTokenAcl path
(none)
server config
virtual host

This is the name of the file containing the ACL that controls access to who can request tokens. Each line that isn't blank or starting with `#` specifies a type of token that the given Kerberos principal may request.

The first space-separated field of each line is an identifier (at present, always a Kerberos principal) which may contain `*` as a wildcard. The second field is either `id`, saying that this Kerberos principal may request id tokens (giving the authenticated identity of the user), or `cred`, saying that this principal may request credentials allowing it to act as the user. For type `cred`, there are two more fields, one giving the type (always `krb5` for now) and the other giving the Kerberos service ticket that may be requested.

# Example ACL File

    # allow anyone with a webauth keytab to request id tokens
    krb5:webauth/*@EXAMPLE.ORG id

    # allow shred to request a service/foobar credential
    krb5:webauth/shred.example.org@EXAMPLE.ORG cred krb5 service/foobar@EXAMPLE.ORG

The `krb5:` prefix on the subject is used to signify that the named principal was authenticated using Kerberos. Currently, krb5 is the only supported mechanism for WebAuth servers to initially authenticate with the WebKDC. Other types of authentication maybe supported in the future.

If the path is not absolute, it will be considered relative to ServerRoot.

# Note

This directive must be set.

The ACL file is cached in memory, but will be re-read automatically if the modification timestamp on the file changes.

# Example

WebKdcTokenAcl conf/webkdc/token.acl
WebkdcTokenMaxTTL
How request old tokens may be before they're considered stale
WebKdcTokenMaxTTL nnnn[s|m|h|d|w]
WebKdcTokenMaxTTL 300s
server config
virtual host

This directive controls how old request tokens may be before they're considered stale. This establishes the limit on how long a user may take while logging in via WebLogin. It also sets a limit on how old the request token used by the WAS to request other tokens via getTokensRequest, but since this is generated with each request and sent in combination with other tokens or authenticators that have their own expirations, this second limit is generally not important.

It is important to keep the clocks of the web application servers and the WebKDC synchronized; if they aren't, all tokens from that application server may be considered stale. This directive should be set to at least as long as the amount of clock skew between the WAS and the WebKDC that should be tolerated.

The units for the TTL are specified by appending a single letter. This letter may be one of `s`, `m`, `h`, `d`, or `w`, which correspond to seconds, minutes, hours, days, and weeks, respectively.

# Example

    # two hour TTL
    WebKdcTokenMaxTTL 2h

WebKdcUserInfoIgnoreFail
Whether to allow password authentication despite user information service failure
WebKdcUserInfoIgnoreFail on|off
WebKdcUserInfoIgnoreFail off
server config
virtual host

By default, if a user information service is configured but either doesn't respond or returns an error, mod_webkdc returns an error and no authentication is permitted. This is the safest action from a security perspective since the system fails closed, but it can create a single point of failure in the user information service that can bring down all web authentication.

If this option is turned on, users will still be able to do basic password authentication (equivalent to what is possible without configuring a user information service) if the user information service doesn't respond or returns an error. Only a password factor will be permitted, and the user will not be able to establish a level of assurance. If the WAS requested any additional factors or a level of assurance, the behavior will be the same as if the user doesn't have those factors or LoA configured.

This directive is only useful in combination with WebKdcUserInfoURL.

# Example

WebKdcUserInfoIgnoreFail on
WebKdcUserJSON
Whether to use the JSON protocol when talking to the user information service
WebKdcUserInfoJSON on|off
WebKdcUserInfoJSON off
server config
virtual host

If this directive is turned on, mod_webkdc will use a JSON protocol for talking to the user information service instead of the older XML-based protocol. Both the parameters to the call and the reply will be in JSON.

This directive is only useful in combination with WebKdcUserInfoURL.

# Example

WebKdcUserInfoJSON on
WebKdcUserInfoPrincipal
Remote principal for user information and multifactor queries
WebKdcUserInfoPrincipal principal
(none)
server config
virtual host

This directive sets the principal of the remote user information and multifactor authentication service. This is the target principal of the WebKDC's authentication if using a user information protocol that uses Kerberos authentication (such as remctl). It is not the principal used by the WebKDC; that's set with WebKdcKeytab. Rather, it's the principal of the remote service, required if the host principal of the system on which it's running is not used.

This directive is only useful in combination with WebKdcUserInfoURL.

# Example

WebKdcUserInfoPrincipal remctl/userdb.example.com@EXAMPLE.COM
WebKdcUserInfoTimeout
Timeout for user information and multifactor queries
WebKdcUserInfoTimeout nnnn[s|m|h|d|w]
WebKdcUserInfoTimeout 30s
server config
virtual host

Sets the timeout for user information service queries and for multifactor authentication. The timeout is enforced on each network exchange with the remote service, not on the total elapsed time for the query, so be aware that a query to a slowly-responding remote service that hands back small bits of data at a time could still take substantially longer in total than the timeout.

The timeout can be set to 0s to disable timeouts. With this setting, mod_webkdc will wait for the remote service for as long as it takes to respond or for the underlying TCP session to time out.

Logins through the WebLogin server will block while the remote service is queried, and this will block the Apache thread or process that's attempting to handle that login. Setting too long of a timeout may therefore allow the WebLogin server to be overwhelmed if a remote server is down or not responding. The default timeout is fairly generous.

For the remctl user information protocol method, setting a timeout requires remctl 3.1 or later. If WebAuth is built against an earlier version, the timeout will be ignored.

The units for the time are specified by appending a single letter. This letter may be one of `s`, `m`, `h`, `d`, or `w`, which correspond to seconds, minutes, hours, days, and weeks, respectively (although the longer intervals are probably not useful).

This directive is only useful in combination with WebKdcUserInfoURL.

# Example

WebKdcUserInfoTimeout 5s
WebKdcUserInfoURL
URL for user information and multifactor queries
WebKdcUserInfoURL url
(none)
server config
virtual host

The WebKDC supports a user information and multifactor authentication service which, if configured, is checked for the user's configured authentication factors, level of assurance, and password expiration time. If this service is available and the user's list of configured factors indicate that they are capable of authenticating with a second factor (besides password), the WebKDC will also trigger multifactor authentication for sites that require it or if the user information service says it's required. This service is also used to determine whether an account requiring random multifactor should have that requirement trigger for this site visit.

This directive configures the URL of the service. Currently, the only supported protocol method is remctl. The server and port are specified with the normal URL syntax, and the port defaults to the normal remctl port. The path portion of the URL must contain only one component and must be the command portion of the remctl command. By default, remctl will assume that the host principal of the provided host name should be used as the authentication target. To change this, see WebKdcUserInfoPrincipal.

The subcommand sent to the remctl server will be `webkdc-userinfo` for the user information query during login and `webkdc-validate` to validate a one-time password authentication.

For specific details of the protocol used to talk to the user information and multifactor authentication service, see the additional protocol documentation that comes with the WebAuth source distribution.

# Example

    # Contact host userdb.example.com and send user webkdc-userinfo
    WebKdcUserInfoURL remctl://userdb.example.com/user