Apache Module mod_webkdc

WebKdcDebug Directive

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

WebKdcFastArmorCache Directive

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.

WebKdcIdentityAcl Directive

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.

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

WebKdcKerberosFactors Directive

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

WebKdcKeyring Directive

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.

WebKdcKeyringAutoUpdate Directive

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.

WebKdcKeyringKeyLifetime Directive

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.

WebKdcKeytab Directive

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.

WebKdcLocalRealms Directive

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.

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

WebKdcLoginTimeLimit Directive

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.

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

# Disable the grace period entirely.
WebKdcLoginTimeLimit 0s

WebKdcPermittedRealms Directive

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.

WebKdcProxyTokenLifetime Directive

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.

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

WebKdcServiceTokenLifetime Directive

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.

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

WebKdcTokenAcl Directive

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.

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

WebkdcTokenMaxTTL Directive

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.

# two hour TTL
WebKdcTokenMaxTTL 2h

WebKdcUserInfoIgnoreFail Directive

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.

WebKdcUserInfoPrincipal Directive

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.

WebKdcUserInfoTimeout Directive

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.

WebKdcUserInfoURL Directive

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.

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