mod_webauth
Support for the WebAuth protocol
External
mod_webauth.c
webauth_module
Apache 2.0 and higher

This module implements the authentication component of a WebAuth Application Server for Apache 2.x. It should be used on each individual Apache server that wants to protect content with WebAuth.

Further details are provided in the WebAuth documentation.

# Minimal Config File

The following example shows the minimum config file required to configure mod_webauth.

## Example

    LoadModule webauth_module modules/mod_webauth.so

    WebAuthKeyring conf/webauth/keyring
    WebAuthKeytab conf/webauth/keytab
    WebAuthServiceTokenCache conf/webauth/service_token_cache
    WebAuthLoginURL https://webkdc/login/
    WebAuthWebKdcURL https://webkdc/webkdc-service/
    WebAuthWebKdcPrincipal service/webkdc

This will enable the module, but not protect any pages. To do that, you will need to add authentication and authorization directives to individual <Location>, <Directory>, or <Files> containers (or equivalents).

# Using WebAuth Authentication

Once configured, basic use of WebAuth is very simple. Simply set up authentication normally, using `AuthType WebAuth` instead of the normal `AuthType Basic`, plus a `require valid-user` directive.

## Example

    <Location /private/>
      AuthType WebAuth
      Require valid-user
    </Location>

This will allow anyone who can authenticate using your WebAuth installation access to this content. You can instead require specific users or require a group. All of the standard Apache authorization directives are supported as normal. For more advanced authorization decisions based on LDAP directory data, see the mod_webauthldap module.

# Environment Variables

This module provides some information as additional environment variables to the SSI and CGI namespace. The generated variables are listed in the table below. For CGI apps that have expectations about and/or restrictions on the names of environment variables they can handle, you can use the WebAuthVarPrefix directive to have additional environment variables set.

Additionally, requesting credentials for a particular request may cause environment variables to get set. For example, requesting Kerberos credentials will result in the KRB5CCNAME environment variable being set.

Variable Name: | Description:
--- | ---
`AUTH_TYPE` | Will be set to `WebAuth`
`REMOTE_USER` | Name of the WebAuth authenticated user (or authorization identity if trusted; see WebAuthTrustAuthzIdentity)
`WEBAUTH_AUTHZ_USER` | Name of the WebAuth authorization identity if present
`WEBAUTH_FACTORS_INITIAL` | Authentication factors user authenticated with
`WEBAUTH_FACTORS_SESSION` | Authentication factors user authenticated with for this particular site
`WEBAUTH_LOA` | Level of Assurance of the user authentication
`WEBAUTH_TOKEN_CREATION` | When the token was created
`WEBAUTH_TOKEN_EXPIRATION` | When the token will expire. If WebAuthInactiveExpire is set then the token may expire sooner due to inactivity.
`WEBAUTH_TOKEN_LASTUSED` | When the token was last used. Only available if WebAuthLastUseUpdateInterval is non-zero.
`WEBAUTH_USER` | Name of the WebAuth authenticated user regardless of authorization identity

## Example Environment Variables

    AUTH_TYPE=WebAuth
    REMOTE_USER=roland
    WEBAUTH_AUTHZ_USER=roland
    WEBAUTH_FACTORS_INITIAL=p,o,o2,m
    WEBAUTH_FACTORS_SESSION=c
    WEBAUTH_LOA=2
    WEBAUTH_TOKEN_CREATION=103872393
    WEBAUTH_TOKEN_EXPIRATION=1038759389
    WEBAUTH_TOKEN_LASTUSED=103872393
    WEBAUTH_USER=schemers

WebAuth can support a separate authentication identity and an authorization identity as seen in the above example. The authentication identity is the identity for which the user presented credentials (such as a password). The authorization identity is the identity that should be used for authorization checks and application access. Normally, these are the same, but the WebKDC can be configured to allow users to assert an authorization identity different than their authentication identity to certain sites. This allows a privileged user to pretend to be another user when accessing a WebAuth-protected resource (for testing purposes, for example).

WEBAUTH_USER will always be set to the authenticated identity, regardless of any authorization identity. WEBAUTH_AUTHZ_USER will always be set to the authorization identity if one was asserted, and will not be set otherwise.

The value of REMOTE_USER is normally the authenticated identity (same as WEBAUTH_USER), but its value depends on whether there is an authorization identity and on whether the WebAuthTrustAuthzIdentity is set. If that directive is set, REMOTE_USER will instead be set to the authorization identity if one is present. The value of REMOTE_USER is also the identity used internally by Apache to check authorization rules and group membership, do LDAP data lookups, and so forth.

When checking for the authenticated username, one should normally use REMOTE_USER, since this is the standard inside Apache and makes the application independent of the authentication system used. This will also work correctly with authorization identities. If you want to use the authentication identity regardless of any authorization identity, use WEBAUTH_USER instead. (You can also use WEBAUTH_USER to ensure that the authentication happened via WebAuth, although that can also be accomplished by checking AUTH_TYPE.) To retrieve the authorization identity, even if it wasn't trusted and used for REMOTE_USER, look at the value of WEBAUTH_AUTHZ_USER.

If this seems excessively confusing, use REMOTE_USER. That will do the correct thing in most circumstances.

# Authentication Factors

Below are the authentication factors that can be required via WebAuth directives or queried from the environmental variables WEBAUTH_FACTORS_INITIAL and WEBAUTH_FACTORS_SESSION.

Code | Factor Name | Description
--- | --- | ---
`c` | cookie | Session authentication via cookie
`d` | device | Device or browser originating the authentication is known to the local security infrastructure, has previously been part of a successful strong authentication, or otherwise is a relatively trusted device as defined by local site policy.
`h` | human | Off-line human verification of the user's identity. This factor should not be required directly; rather, it is used by (for example) local support staff to add a factor, and hence add the multifactor factor, for a user who doesn't have access to their normal authentication method but has established their identity via some off-line process.
`k` | Kerberos | Session authentication via Kerberos authentication
`m` | multifactor | Session or initial authentication via multiple independent authentication factors (site-defined)
`mp` | mobile push | User approved an out-of-band push notification to a mobile device
`o` | OTP | Session or initial authentication via one-time password
`o#` | OTP | A more specific subset of `o`. Number indicates a specific OTP mechanism as defined by the local site, with higher numbers indicating stronger methods
`p` | password | Session or initial authentication via traditional password
`rm` | random multifactor | User has a random chance of being challenged for a second factor; frequency of challenges is site-defined
`u` | unknown | Session or initial authentication via an unknown method
`v` | voice | User approved authentication via voice telephone call
`x` | X.509 | Session or initial authentication via some form of X.509 authentication
`x#` | X.509 | A more specific subset of `x`. Number indicates a specific X.509 mechanism as defined by site, with higher numbers indicating stronger methods

# Using WebAuth with Proxy Servers

WebAuth authentication and authorization directives can be used in <Proxy> blocks just as in any other configuration block, so to protect a proxy where the remote proxy doesn't need to know about the authenticated user, just protect that resource like any other resource.

Sometimes, it's also useful to pass the authentication information to the remote site. This option should only be used as a last resort when the target server is unable to directly support WebAuth. HTTP headers are not secure and can easily be forged. The target server should only accept connections from the proxy server running `mod_webauth`.

To do this with a ProxyPass proxy, it's easiest to use mod_headers to set extra headers based on the values of `WEBAUTH_` environment variables. The remote web application then should pull its authentication information from those headers.

For example, lets say you want to pass `WEBAUTH_USER` through to a proxy server. Assuming you've loaded `mod_headers` and can therefore use the `RequestHeader` directive, you could do the following:

## Example

    <Location /someplace>
      AuthType WebAuth
      require valid-user
      ProxyPass http://otherhost.stanford.edu/
      ProxyPassReverse http://otherhost.stanford.edu/
      RequestHeader set "X-WEBAUTH-USER" "%{WEBAUTH_USER}e"
    </Location>

The `RequestHeader` directive causes the `X-WEBAUTH-USER` header to get set with the value of the `WEBAUTH_USER` environment variable. The value of this header is then often available in the environment for the web application running on the remote system.

## Note: WebAuth Cookies and Referer Header

`mod_webauth` strips out any cookies that start with the prefix `webauth_`, so they do not get forwarded to the target server, it also strips out any WebAuth-related information in the Referer header.

## Note: WebAuthDoLogout

If you are planning on using WebAuthDoLogout with your proxied server, you should be aware that once you tell Apache to proxy a URL namespace (like `/someplace/`), then you can't have local `Location` directives for URLs within that namespace, like `/location/logout`. Instead, you'll need to create a that script on the target server, and have it remove any cookie that starts with `webauth_`. (Unfortunately, it won't see those cookies due to the above cookie stripping behavior, so you'll have to hard-code the cookie names that will be used.)

# Perl Integration

In order to use mod_webauth with Perl, you need to first WebAuth-protect the pages that are served by the CGI Perl scripts. For example, lets assume that all pages under http://yourserver/private/ are to be protected:

## Apache Directives Example

    <Location /private/>
      AuthType WebAuth
      Require valid-user
    </Location>

Then, in order to determine the user's identity from the Perl script, it is simply a matter of accessing the environment variables set by mod_webauth within your Perl script:

## Perl Example

    my $REMOTE_USER = $ENV{'REMOTE_USER'};
    print "Content-Type: text/plain\n\n";
    print "The authenticated user is $REMOTE_USER\n";

Any of the environment variables described in the environment variables section may be accessed this way.

# PHP 4.x and 5.x Integration

Using mod_webauth with PHP is very similar to using it from Perl. You need to first WebAuth-protect the pages that are served by the PHP scripts. For example:

## Apache Directives Example

    <Location /private/>
      AuthType WebAuth
      Require valid-user
    </Location>

Then, in order to determine the user's identity from the PHP script, you can either use the PHP getenv function, or access the special `$_SERVER` array variable. For example:

## PHP Example

    $WEBAUTH_USER = getenv('WEBAUTH_USER');

    # alternative, using the $_SERVER 'superglobal' array:
    # $WEBAUTH_USER = $_SERVER['WEBAUTH_USER'];

    print "The authenticated user is $WEBAUTH_USER\n";

In looking at the source for PHP 4.3, it appears that the `getenv` is looking only in the `$_SERVER` array, so there is a one-to-one mapping between the two. Oddly enough, getenv isn't looking the `$_ENV` array. See the PHP documentation for more information on predefined variables in PHP.

Any of the environment variables described in the environment variables section may be accessed this way.

# Java/Tomcat/mod_jk Integration

Using mod_webauth with mod_jk requires some additional configuration of mod_jk in order to pass environment variables to the Java servlet. So, in addition to WebAuth-protecting the pages served by Tomcat, you also need to specify which environment variables you want to pass. For example:

## Apache Directives Example

    # WebAuth-protect /private/
    <Location /private/>
      AuthType WebAuth
      Require valid-user
    </Location>

    # Send everything for /private/ to worker1
    JkMount /private/* worker1
    # WebAuth-related environment variables to pass
    JkEnvVar WEBAUTH_USER "<UNSET>"
    JkEnvVar REMOTE_USER "<UNSET>"
    JkEnvVar AUTH_TYPE "<UNSET>"
    JkEnvVar WEBAUTH_TOKEN_CREATION "<UNSET>"
    JkEnvVar WEBAUTH_TOKEN_EXPIRATION "<UNSET>"

If all you are interested in is REMOTE_USER, then you don't need to pass the other variables as well.

In order to determine the user's identity from the servlet, you need to use the `getAttribute` method on the `request` object.

## JSP Example

    WEBAUTH_USER is set to:
    <% out.print (request.getAttribute("WEBAUTH_USER")); %>

Any variables you configure mod_jk to pass via `JkEnvVar` will end up as a request attribute as opposed to being accessible by `java.lang.System.getenv`, which is deprecated.

## Note

It appears that mod_jk requires you specify a default value for the environment variables in the event that they are unset. A value of `""` was not allowed, so I picked the special value `"<UNSET>"` for this example. If all your pages are WebAuth-protected, then this default value will never be used.

You will also need to explicitly turn off Tomcat authentication in the `<Connector>` definition in the Tomcat `server.xml` file. For example:

## Connector Example

    <Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
        port="8009" minProcessors="5" maxProcessors="75"
        tomcatAuthentication="false"
        acceptCount="10" debug="0"/>

Be aware that Apache and Tomcat parse semicolons in URLs differently. Without careful configuration, attackers can bypass WebAuth protection when accessing a resource in Tomcat by exploiting this difference. In Apache, the URLs `/srvlet/secret` and `/srvlet/secret;hello` are different URLs, but Tomcat considers the part after a semicolon to be a URI path parameter, ignores it, and treats them both as the same URL. Therefore, if only `/srvlet/secret` is protected in Apache (with a `<Location>` directive, for example), an attacker can bypass that protection but still access the same underlying URL in Tomcat.

To protect against this, any `<Location>` directive protecting a specific URL within a larger URL namespace proxied to Tomcat should allow for any trailing URI path parameters, as in the following example:

## Access Control Example

    # DO NOT USE THIS -- insecure!
    <Location "/srvlet/secret">
        AuthType WebAuth
        require valid-user
    </Location>

    # Instead, use this or some other regex that matches the path with URI
    # path parameters inserted anywhere.  Be aware that they can be in each
    # path component!  (But if JkMount refers to /srvlet, then /srvlet;hello
    # won't be sent to Tomcat by Apache and therefore is safe.)
    <Location ~ "/srvlet/secret(;.*)?$">
        AuthType WebAuth
        require valid-user
    </Location>

This problem applies to any Apache authentication mechanism applied to URLs that are proxied to Tomcat. It is not specific to WebAuth.

# Requesting Credentials

One of the features of WebAuth is the ability to request credentials on behalf of the user for a particular request (or group of requests). This allows authorized application servers to act on behalf of the user.

Depending on the credential type (and always for Kerberos tickets, which are currently the only supported credentials), temporary files containing credentials may need to be created. These credentials will be stored in the directory specified by the WebAuthCredCacheDir directive.

The WebAuthCred directive is used to specify which credentials a particular request may need. Credentials are not actually requested from the WebKDC until a page with the WebAuthUseCreds directive set to "on" is served. At that point, they will be cached (encrypted) in cookies and used to satisfy future requests.

Saving credentials on every single request (for example, an image or static page) is expensive, since it may involve decrypting credentials stored in a cookie, processing them, and storing them in a temporary file. The WebAuthUseCreds directive is used to control which requests will actually go through this process.

The following example shows one scenario where every page under /myapp/ is WebAuth-protected, and every page under /myapp/commands/ requires the use of two Kerberos credentials.

## Example

    # This first WebAuthCred directive will cause us to acquire a proxy token
    # on the initial redirect when determining the user's identity.  It saves
    # an extra redirect later on when we actually use/acquire credentials.

    <Location /myapp/>
      AuthType WebAuth
      require valid-user
      WebAuthCred krb5
    </Location>

    # These next WebAuthCred directives will cause us to acquire two
    # credentials from the WebKDC, since WebAuthUseCreds is on.

    <Location /myapp/commands/>
      WebAuthUseCreds on
      WebAuthCred krb5 host/slapshot.stanford.edu@stanford.edu
      WebAuthCred krb5 host/lichen.stanford.edu@stanford.edu
    </Location>

## Warning for Load-Balanced Pools

If you are using delegated credentials with a pool of servers behind a load balancer (see the section on load balancing), each system in the pool must use the same Kerberos identity when requesting credentials. Otherwise, the delegated credentials will be locked to the one principal that requested them and the other hosts will not be able to use them, which will cause problems if a given client moves from one pool member to another.

## Warning for Active Directory

If you are using Active Directory as your KDC, be aware that Active Directory Kerberos tickets can be relatively large because they contain extra authorization information. This means the corresponding cookies set by WebAuth that hold delegated credentials can also be large, and in combination with other cookies may exceed the maximum cookie size allowed for by the HTTP protocol. If you run into problems, you can work around this by suppressing the PAC authorization information for the services that don't need it in your Active Directory.

# Debugging mod_webauth

If you are having trouble getting `mod_webauth` configured, you can enable the `webauth` handler and point your browser at the configured URL to get some information on whether or not mod_webauth is configured correctly.

## Note

Just to be safe, you should probably disable the `webauth` handler after you have `mod_webauth` configured correctly.

## Example

    # WebAuthDebug must be on
    WebAuthDebug on

    <Location /webauth-status>
      SetHandler webauth
      Order allow,deny
      Allow from all
    </Location>

# Setting up load-balanced WebAuth servers

WebAuth was designed so that it would be fairly easy to setup multiple WebAuth servers for load balancing and redundancy. In order to achieve this, the WebAuth keyring has to be shared between the WebAuth servers. The Kerberos keytab file does not have to be shared; each system can use a separate keytab file. (There is one exception to this last rule: credential delegation. If you are using credential delegation with a load-balanced pool, all servers in the pool must share the same Kerberos keytab file as well as the keyring. See the warning under requesting credentials for more information.)

## Note

The keyring file should be securely transferred from the master to the slave(s) using a program like `scp` or kerberized `rcp`.

By convention, one of the WebAuth servers should be designated as the master and other servers should be designated as slaves. The keyring should only be updated on the master and pushed manually to the slaves.

The WebAuth keyring file is specified using the WebAuthKeyring directive. This file contains the WebAuth server's private AES key(s). If you are running multiple WebAuth servers, you must turn off automatic updating of the keyring file on restarts. This is done using the WebAuthKeyringAutoUpdate directive:

## Turning off auto update

WebAuthKeyringAutoUpdate off

Once auto update is turned off, the keyring file will not get automatically updated and can manually be copied across all the servers. The keys in the keyring file still need to be changed periodically, and the `wa_keyring` command can be used to do this. This command would be run on the keyring file on the master, at which point it would 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 7d

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 servers. Old keys in the keyring file should also periodically be removed. This can manually be done with `wa_keyring` using the `list` and `remove` commands. For example:

## Manually remove old keys

    $ wa_keyring -f ./keyring list
    Path: ./keyring
    id  Created            Valid after        Fingerprint
     0  2003-02-13 12:43:25  2003-02-13 12:43:25  664b48642f741ae343ef5ea46a8768e8
     1  2003-03-12 16:21:57  2003-03-12 16:21:57  7c4971e760f75525bba277a308c092c0

    $ wa_keyring -f ./keyring remove 0

Or it can be done automatically, using the `gc` command:

## Automatically removing old keys

    # Remove any keys with a valid after date older then 90 days
    $ wa_keyring -f ./keyring gc -90d

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

## Example

    WebAuthKeyring conf/webauth/keyring
    WebAuthKeytab conf/webauth/keytab
    WebAuthKeyringAutoUpdate off

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. For example:

## Monthly Key maintenance

    # Generate a new key that will be valid in 2 days.
    wa_keyring -f conf/webauth/keyring add 2d

    # Remove keys that have been around for more then 60 days.
    wa_keyring -f conf/webauth/keyring gc 60d

    # Copy the new keyring to all of the slaves.
    for slave in $slaves ; do
        scp conf/weauth/keyring $slave:{path-on-slave}
    done

    # Restart the master and all the slaves at any point before the new key is
    # valid.

# Manual License

Copyright 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012, 2013, 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.

WebAuthAppTokenLifetime
Lifetime of app-tokens we create.
WebAuthAppTokenLifetime nnnn[s|m|h|d|w]
(lifetime of id-token returned from WebKDC)
directory

This directive controls how long the app-token (the main cookie containing a user's authenticated identity) is valid for. If not specified, the expiration time in the id-token returned from the WebKDC is used, which is the recommended configuration.

To be effective, this directive should be used with the WebAuthForceLogin directive, otherwise single-sign-on will automatically log the user back in when the token expires.

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

# Example

    # create an app-token valid for 2 hours
    WebAuthAppTokenLifetime 2h

WebAuthAuthType
Additional AuthType name to support
WebAuthAuthType StanfordAuth
(none)
server config
virtual host

This sets an additional `AuthType` name that will be treated the same as `WebAuth` when used with the `AuthType` directive. The only interesting value to use is `StanfordAuth`, which enables some backward compatibility code for transitioning from WebAuth 2.x.

Setting this directive to `StanfordAuth` and then using `StanfordAuth` in an `AuthType` directive will also cause two additional environment variables to get set: `SU_AUTH_USER` and `SU_AUTH_AGE`.

# Warning

This directive is deprecated and will be removed in a future version of WebAuth.

# Example

WebAuthAuthType StanfordAuth
WebAuthCred
Which credentials to acquire
WebAuthCred type [service]
(none)
directory

This directive specifies which credentials a particular request may need. It should be used should be used in conjunction with the WebAuthUseCreds directive.

Note that service is optional. If service is not present, then this is used to indicate that a page further down in the hierarchy will eventually acquire credentials of the specified type by specifying credentials with a service name and setting WebAuthUseCreds to "on".

This directive may be used multiple times in the same location to specify that multiple credentials are required.

# Example

    # get and use the following krb5 credential on every
    # request under /myapp/.
    <Location /myapp/>
      AuthType WebAuth
      require valid-user
      WebAuthCred krb5 host/slapshot.stanford.edu@stanford.edu
    </Location>

WebAuthCredCacheDir
Name of the directory containing cached credentials
WebAuthCredCacheDir path
(none)
server config
virtual host

This is the name of the directory where credentials are cached for the duration of a single request.

If the path is not absolute, then it will be treated as being relative to ServerRoot.

# Note

This directive must be set if the WebAuthCred and WebAuthUseCreds directives are used.

# Example

WebAuthCredCacheDir conf/webauth/credcache
WebAuthCookiePath
Path scope of cookies set by the module
WebAuthCookiePath scope
/
directory
.htaccess

Normally, all WebAuth cookies use a path of "/" and will be sent by the browser for all requests to that server or virtual host. This setting can be used to restrict the scope of cookies (which include app, proxy, and cred cookies) to a particular URL path prefix. This may be useful if different sections of a virtual host must be handled differently by user information service policy and therefore must use separate credential sets. It allows different portions of the same virtual host to be treated as separate destination "sites" from the perspective of single sign-on and browser authentication credential management.

The scope argument should be the URL or a prefix of the URL by which the resource affected by this directive is accessed. The module has no way of checking this, so use care in setting the scope. An incorrect scope may result in cookies being set but not returned by the browser, which can cause a redirect loop between the WebAuth-protected site and the WebLogin service.

The scope argument follows the normal rules for path-based scope for cookies using the "path=" cookie parameter as described in RFC 6265.

# Warning

Currently, the mod_webauth module does not deal properly with requests containing multiple cookies of the same name. The first cookie will be used and the rest ignored, which results in undefined behavior since the order of cookies is not deterministic. Therefore, if the WebAuthCookiePath directive is used within a virtual host, all WebAuth-protected URLs in that virtual host should use this directive and all protected URLs should be within one and only one path scope. In other words, ensure that the browser will know that only one set of cookies could apply to any given URL so that it will never send more than one cookie with the same name.

This restriction will hopefully be lifted in future versions of WebAuth.

# Example

    # In the following example, no other URLs in this virtual host should be
    # protected by WebAuth to avoid creating potentially conflicting cookies
    # with a path scope of /.
    <Location "/content">
      AuthType WebAuth
      Require vald-user
      WebAuthCookiePath /content
    </Location>
    <Location "/manage">
      AuthType WebAuth
      Require user admin1 admin2
      WebAuthCookiePath /manage
    </Location>

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

Whether or not to do extra debugging in the Apache error log. You should also set Apache's `LogLevel` to `debug` as well.

# Example

    WebAuthDebug on
    LogLevel debug

WebAuthDoLogout
Destroy all WebAuth-related cookies
WebAuthDoLogout on|off
WebAuthDoLogout off
directory
.htaccess

This directive controls whether or not all WebAuth-related cookies are removed if the user accesses this URL. This directive also enables the WebAuthDontCache directive for the given location.

# Example

    <Location /myapp/logout>
      WebAuthDoLogout on
    </Location>

# Note

WebAuth-related cookies are all cookies that start with the prefix "webauth_", except for those beginning with "webauth_wpt" or "webauth_wft". The latter are single sign-on or persistent factor cookies used with the WebLogin server and aren't removed by this directive.

WebAuthDontCache
Turn on expire header
WebAuthDontCache on|off
WebAuthDontCache off
directory
.htaccess

Setting this to `on` will cause the following headers to be included in the response to tell browsers not to cache the returned document.

Header Name | Header Value
--- | ---
`Expires` | (current time)
`Pragma` | no-cache
`Cache-Control` | no-cache

It is recommended this only be turned on for sensitive documents and not all documents (and images) on the server.

# Example

WebAuthDontCache on
mod_expires
WebAuthExtraRedirect
Whether or not to do an extra redirect upon return from the WebKDC
WebAuthExtraRedirect on|off
WebAuthExtraRedirect on
server config
virtual host
directory
.htaccess

When browsers get redirected back from the WebKDC, tokens will be returned in the URL, by appending the string "`?WEBAUTHR=...;;WEBAUTHS=...;`" to the URL.

This directive controls whether or not an extra redirect will be sent to the browser, with this information removed from the URL after the user has been authenticated. The benefit of performing the extra redirect is the user's won't see the extra WebAuth information in the URL, and won't be able to bookmark it, etc. Note that bookmarking a URL with the extra information shouldn't really cause any problems, as the tokens in the extra information will only be valid for a limited amount of time (see WebAuthTokenMaxTTL), after which they will be ignored.

The downside to enabling this directive is the extra redirect will require another round-trip from the server to the user's browser, and under certain circumstances maybe also trigger a caching bug in the user's browser (though hopefully this should never happen).

# Example

    <Location /myapp/>
      WebAuthExtraRedirect off
      ...
    </Location>

# Compatibility

In versions of WebAuth prior to 3.5.0, the default for WebAuthExtraRedirect was off. Also, prior to 3.5.0, this directive was only accepted in directory and .htaccess configuration contexts, not in the server configuration or virtual host configurations.

WebAuthFailureURL
The URL browsers get redirected to when a fatal mod_webauth error occurs
WebAuthFaliureURL url
(none)
directory

This is the URL browsers get redirected to when mod_webauth encounters a fatal error. If it is not set, then the server will return a "500 Internal Server Error" when a fatal error occurs.

# Example

WebAuthFailureURL /app/sorry.html
WebAuthForceLogin
Forces interactive authentication when user is not authenticated
WebAuthForceLogin on|off
WebAuthForceLogin off
directory

This directive controls whether or not interactive authentication will be forced if the user needs to be redirected to the WebLogin server for authentication.

By default, the WebLogin server may set cookies for the user after their first authentication and use those cookies for any subsequent authentication until the user's credentials expire. The user may therefore not have to present credentials again, which poses some risk if the user walked away from a system without destroying browser cookies. This directive can be used to force an interactive authentication if the user needs to go to WebLogin.

Interactive is defined as involving a login token, which in practice means either a password or an OTP authentication via WebLogin. The normal expected behavior is that that the local WebLogin server will re-prompt the user for their password, but some other authentication mechanism may be possible depending on local WebLogin and WebKDC configuration.

Compare this directive to WebAuthRequireSessionFactor to determine which is the most appropriate for your use case. Note that WebAuthRequireSessionfactor only requires that the authentication be very recent (as controlled by a WebKDC configuration option), not that it be repeated for each separate site.

Be aware that setting this directive to true will make asserting an authorization identity (see WebAuthTrustAuthzIdentity) impossible unless the user is prompted for the authorization identity as part of the initial authentication, since this directive will not allow the user to select a different authorization identity without reauthenticating.

# Example

    # force the user to login, and create an app-token
    # that only lasts for 20 minutes
    <Location /myapp/>
      AuthType WebAuth
      Require valid-user
      WebAuthForceLogin on
      WebAuthAppTokenLifetime 20m
    </Location>

WebAuthHttpOnly
Whether or not to set WebAuth cookies HttpOnly
WebAuthHttpOnly on|off
on
server config
virtual host

This directive controls whether the HttpOnly flag is set on WebAuth session cookies. It is turned on by default. In the unusual event that Javascript needs to be able to read these cookies, this directive can be used to turn off the flag.

Be aware that the structure and format of the WebAuth cookies are an internal implementation detail and decoding them or modifying them outside of the WebAuth code itself is not recommended. If you need to turn this directive off, that normally indicates that you are doing something unsupported with the WebAuth cookies.

# Example

WebAuthHttpOnly off
WebAuthInactiveExpire
Expiration period for app tokens that haven't been used recently
WebAuthInactiveExpire nnnn[s|m|h|d|w]
(disabled)
directory

Duration of inactivity allowed before an app token (webauth_at cookie) is considered expired and re-auth occurs. Setting this requires mod_webauth to periodically update the webauth_at cookie, based on the setting of the WebAuthLastUseUpdateInterval directive.

To be effective, this directive should be used with either WebAuthForceLogin or WebAuthRequireSessionFactor. Otherwise, single-sign-on will automatically log the user back in when the token expires due to inactivity. Additionally, this value should be higher then the value of WebAuthLastUseUpdateInterval. Otherwise, the cookie will expire before the last-used time is updated.

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

# Example

    # timeout an app-token if it isn't used for more
    # then 20 minutes
    WebAuthInactiveExpire 20m
    # update the last-used-time in the cookie if it's older
    # then 10 minutes
    WebAuthLastUseUpdateInterval 10m

WebAuthKeyring
Name of the file containing the WebAuth keyring
WebAuthKeyring path
(none)
server config
virtual host

This is the name of the file containing the WebAuth keyring, which is a file that contains the server's private AES key(s). 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 doing WebAuth. This maintains proper privilege separation by assigning each user a separate keyring.

If the path is not absolute, then it will be treated as being relative to `ServerRoot`.

# Note

This directive must be set.

# Example

WebAuthKeyRing conf/webauth/keyring
WebAuthKeyringAutoUpdate
Whether or not we auto-update the keyring file
WebAuthKeyringAutoUpdate on|off
WebAuthKeyringAutoUpdate 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 the keyring file can be manually updated.

# Example

WebAuthKeyringAutoUdpate off
WebAuthKeyringKeyLifetime
Lifetime of keys in the keyring if we auto-update
WebAuthAKeyringKeyLifetime nnnn[s|m|h|d|w]
WebAuthKeyringKeyLifetime 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. 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, which can either be s, m, h, d, or w, which correspond to seconds, minutes, hours, days, and weeks respectively.

# Example

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

This is the name of the Kerberos keytab file. If principal is not specified, then the first principal in the keytab file be used.

If the path is not absolute, then it will be treated as being relative to `ServerRoot`.

# Note

This directive must be set.

# Example

WebAuthKeytab conf/webauth/keytab webauth/slapshot.stanford.edu
WebAuthLastUseUpdateInterval
How often to update the main webauth cookie
WebAuthLastUseUpdateInterval nnnn[s|m|h|d|w]
WebAuthLastUsedUpdateInterval 0
directory

This value determines how often we update the webauth_at cookie to indicate when the token was last used. Setting this too small will cause too many cookie updates. A value of 0 will disable updating of the cookie.

This directive is normally only used with WebAuthInactiveExpire, though it can be used independently if you just need the `WEBAUTH_TOKEN_LASTUSED` environment variable updated.

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

# Example

    # timeout an app-token if it isn't used for
    # more then 20 minutes
    WebAuthInactiveExpire 20m
    # update the last-used-time in the cookie if it's older
    # then 10 minutes
    WebAuthLastUseUpdateInterval 10m

WebAuthLoginCanceledURL
URL to return to if user cancels out of login
WebAuthLoginCanceledURL url
(none)
directory
.htaccess

This directive controls which URL the user is returned to if they have to login, but hit the cancel button while logging in. Normally, the cancel option will not be displayed, but if this directive is set, the user will be shown an option to cancel logging in on the WebLogin screen.

# Example

WebAuthLoginCanceledURL /nonwebauth/info.html
WebAuthLoginURL
The URL browsers get redirected to when the user is unauthenticated
WebAuthLoginURL url
(none)
server config
virtual host

This is the URL browsers get redirected to when the user is unauthenticated and needs to either login or reuse an existing single-sign-on credential. This should alway use SSL.

# Note

This directive must be set.

# Example

WebAuthLoginURL https://weblogin.stanford.edu/login
WebAuthOptional
Whether or not to require the use to authenticate
WebAuthOptional on|off
off
directory
.htaccess

Normally, if an unauthenticated user attempts to access a directory protected by WebAuth, they will be redirected to the WebLogin server to authenticate. This directive allows that authentication to be deferred. If this option is set to on, an unauthenticated user will still be permitted access to the protected resource (even with `require valid-user` in effect), unless they're prohibited by some other authorization rule. Unauthenticated users will not have the REMOTE_USER, WEBAUTH_USER, or AUTH_TYPE environment variables set. If the user has already authenticated, then all the environment variables will be set as normal.

This directive is normally used to protect CGI scripts or other dynamic content that will then inspect the REMOTE_USER environment variable and show different content based on whether the user has authenticated or not. Generally, such content will include a login link to a page protected by WebAuth with WebAuthOptional set to off, so that the user can authenticate if they wish. After that authentication, subsequent visits to content with WebAuthOptional set to on will have authentication information available in the environment.

# Example

WebAuthOptional on
WebAuthPostReturnURL
URL to return to after authenticating during a POST
WebAuthPostReturnURL url
(none)
directory
.htaccess

This directive controls which URL the user is returned to after authenticating with the WebKDC when the HTTP method was a POST. By default, mod_webauth will return 401 (UNAUTHORIZED), as it is impractical to try and recover from a POST that failed due to no authentication.

# Example

    # if unauthenticated when accessing a URL via a POST,
    # authenticate and return to front-page
    WebAuthPostReturnURL /myapp/

WebAuthRequireInitialFactor
Required factors for initial authentication
WebAuthRequireInitialFactor factor [factor ...]
(none)
directory
.htaccess

Normally, WebAuth will accept any authentication method and allow access to the protected resource. This directive is used to require that the user's initial authentication be done with a particular factor. The value is a space-separated list of factors, all of which are required. If any of those factors were not used for the initial authentication, the user will be sent back to the WebLogin server to reauthenticate.

The initial authentication is the authentication used to obtain single sign-on cookies (if any). That authentication may have been done immediately before going to this web site, or earlier to obtain single sign-on credentials. See WebAuthRequireSessionFactor to control the factors used to authenticate to this specific resource, or WebAuthRequireLOA for a different approach to these sorts of restrictions.

# Example

WebAuthRequireInitialFactor p o
WebAuthRequireLOA
Required level of assurance for authentication
WebAuthRequireLOA loa
0
directory
.htaccess

Normally, WebAuth will accept any authentication method and allow access to the protected resource. This directive is used to require that the user's authentication meet a particular level of assurance.

A level of assurance is an integer number whose definition varies from site to site, except that larger numbers indicate a stronger assurance of the user's authentication and identity than smaller numbers. Level of assurance may combine multiple factors, such as binding of identity (whether the user presented identification when obtaining their account credentials), method of authentication, and other site-defined information. This directive should be used in conjunction with site-specific supplemental documentation of what the level of assurance numbers mean for that site.

# Example

WebAuthRequireLOA 2
WebAuthRequireSessionFactor
Required factors for session authentication
WebAuthRequireSessionFactor factor [factor ...]
(none)
directory
.htaccess

Normally, WebAuth will accept any authentication method and allow access to the protected resource. This directive is used to require that the user's session authentication be done with a particular factor. The value is a space-separated list of factors, all of which are required. If any of those factors were not used for the session authentication, the user will be sent back to the WebLogin server to reauthenticate.

The session authentication is the authentication used to access this particular resource (or, more specifically, to obtain an application authentication cookie scoped to include this resource). This will match the initial authentication if the user did not use any single sign-on method, if WebAuthForceLogin is set), or if the user has authenticated very recently, but may be different if single sign-on is in use. In most situations, one should instead use WebAuthRequireInitialFactor to control the initial authentication factors and allow single sign-on to work normally. See WebAuthRequireLOA for a different approach to these sorts of restrictions.

# Example

WebAuthRequireSessionFactor m
WebAuthRequireSSL
Whether SSL is required to access a WebAuth-protected resource
WebAuthRequireSSL on|off
WebAuthRequireSSL on
server config
virtual host

Normally, all WebAuth-protected resources must be accessed via SSL. Attempts to access a WebAuth-protected resources without SSL will either be rejected with an authorization denied error (the default) or will be redirected to the equivalent SSL URL (if WebAuthSSLRedirect is set to `on`).

If this directive is set to `on`, access to a WebAuth-protected resource is permitted without the protection of SSL.

# Warning

Turning off this directive can create a significant security vulnerability. Without required use of SSL, there is no protection for the WebAuth app token. Anyone in the network path from the client to the server can trivially steal the token and then authenticate to that server as that user. Under normal circumstances, this directive should never be turned off.

There are, however, two circumstances in which turning off this directive might make sense.

One is if the WebAuth-protected resource is behind a separate SSL accelerator and connected to it via a trusted network link. In this case, by the time Apache sees the request, it appears to not be using SSL, but the request has SSL protection on all untrusted network connections. In this case, it may be necessary to turn off this directive and to turn on WebAuthSSLReturn so that the client is returned to the correct URL after authentication.

The other case where turning this directive off may make sense is if WebAuth is being used to protect a proxy for low-value, low-security content where theft of the authentication credentials for that site is not a concern. This may be the case if, for example, WebAuth is being used to protect a subscription service that's not of sufficiently high value that theft of authentication credentials is an expected risk. Even in this case, requiring SSL is strongly preferred, but some PAC-based proxy configurations may not permit forcing SSL to the proxy server.

# Example

    # This server is behind an SSL accelerator, so Apache only sees
    # non-SSL traffic.  Permit non-SSL WebAuth access, but ensure the
    # return URL for authentication tells the client to use SSL.
    WebAuthRequireSSL off
    <Location />
      WebAuthSSLReturn on
    </Location>

WebAuthReturnURL
URL to return to after authenticating
WebAuthReturnURL url
(url user originally requested)
directory
.htaccess

This directive controls which URL the user is returned to after authenticating with the WebKDC. By default, they will return the URL they originally requested.

# Example

    # if unauthenticated when accessing a URL, authenticate
    # and return to front-page
    WebAuthReturnURL /myapp/

WebAuthServiceTokenCache
Name of the service-token cache file.
WebAuthServiceTokenCache path
(none)
server config
virtual host

This is the name of the service-token cache file. This file is used to maintain a cached copy of the service-token that gets shared between all the web server's child processes. It will get generated and maintained automatically.

If the path is not absolute, then it will be treated as being relative to `ServerRoot`.

# Note

This directive must be set.

# Example

WebAuthServiceTokenCache conf/webauth/service_token_cache
WebAuthSSLRedirect
Redirect to https when accessing a WebAuth-protected page via http
WebAuthSSLRedirect on|off
WebAuthSSLRedirect off
server config
virtual host

If a user attempts to access a WebAuth-protected page via `http` instead of `https` and this directive is turned off, then access will be denied. If this directive is tuned on, then the user will be redirected to the same URL using `https` instead of `http`. Once accessing pages using `https`, they will remain accessing pages via `https` unless the application redirects the user back to `http`.

# Note

If the server is not configured to run SSL on the default port, then the WebAuthSSLRedirectPort directive must be used to specify which port to redirect the user to.

# Example

WebAuthSSLRedirect on
WebAuthSSLRedirectPort
port to use when redirecting the user to https
WebAuthSSLRedirectPort port
WebAuthSSLRedirectPort 443
server config
virtual host

This is used in conjunction with the WebAuthSSLRedirect directive and controls which port the user is redirected to when redirecting them to the `https` version of the URL. This is useful during development if you run the Apache server on ports 8080 and 8443, for example.

# Example

    WebAuthSSLRedirect on
    WebAuthSSLRedirectPort 8443

WebAuthSSLReturn
Sets the return URL to be https
WebAuthSSLReturn on|off
WebAuthSSLReturn off
directory
.htaccess

If a user connects to a WebAuth-protected page via http, and needs to be authenticated, then this directive will cause the return URL to be converted to https. For this directive to have any meaning, usually WebAuthRequireSSL must also be off; otherwise, the access will either be denied or redirected to https anyway before this directive can have any effect.

This directive should be set, in conjunction with WebAuthRequireSSL, when the page is actually protected by SSL from the perspective of the browser but not from the perspective of Apache. This is common when the Apache server is behind a load balancer that decrypts SSL, or is otherwise behind an SSL offload proxy.

# Example

    <Location /myapp/>
      AuthType WebAuth
      Require valid-user
      WebAuthRequireSSL off
      WebAuthSSLReturn on
    </Location>

WebAuthStripURL
Whether or not to strip WebAuth information from the internal URL
WebAuthStripURL on|off
on
server config
virtual host

This directive controls whether the WebAuth module strips WebAuth information from the URL before processing it. If set to on (the default), the WEBAUTHR and WEBAUTHS strings are stripped from Apache's internal knowledge of the URL before <Directory> and <File> blocks are processed and other modules, CGI scripts, and similar applications will not see the WebAuth data.

Normally, you should always leave this directive on. The only reason to turn it off is if you have an application that wants to do its own WebAuth handling, running on a server that also has mod_webauth enabled. If you do turn this directive, you should also enable WebAuthExtraRedirect or your web applications will see unexpected data in their URLs that they won't know what to do with.

This unfortunately can only be set usefully at the server or virtual host level due to the way that Apache processes requests.

# Example

WebAuthStripURL off
WebAuthSubjectAuthType
Type of subject authenticator the WebKDC will use in the returned id-token
WebAuthSubjectAuthType type
WebAuthSubjectAuthType webkdc
server config
virtual host

When mod_webauth needs to make a request for an id-token, it needs to specify what type of subject authenticator that it expects returned. This directive configures which type of subject authenticator is requested by type:

`webkdc`

  This is the default.

  When this type of subject authenticator is used, the WebKDC will place the already verified username in the returned id-token (encrypted, of course). When mod_webauth gets back the id-token, it will trust that the WebKDC as sufficiently authenticated the user, and use the returned username.

`krb5`

  When this type of subject authenticator is used, the WebKDC will use the user's Kerberos credentials to make a `krb5_mk_req` call, using the requesting web server's Kerberos principal. When mod_webauth gets back the id-token, it will then use it's keytab to verify the subject authenticator using `krb5_rd_req`.

  This means that, even if the WebKDC is compromised, a user's identity cannot be forged unless that user happens to be logged in and using the WebKDC.

  Setting this subject auth type will make all id tokens about 500 bytes longer then when using a type of `webkdc`. This may cause problems with the HTTP header limit if the site uses other large cookies, or uses Active Directory as the Kerberos KDC (which may make Kerberos tickets significantly longer).

  This setting will also cause mod_webauth to ignore all authorization identities (since they cannot be independently verified), meaning that WebAuthTrustAuthzIdentity directives will be ignored.

  Also be aware that using this option means that the WebAuth server will not get the benefit of any identity canonicalization or mapping that is done by the WebLogin server. Instead, it will authenticate the user as the principal present in the Kerberos authenticator, converted to a local name through the normal Kerberos local name mapping mechanism. This may be a feature or a drawback depending on the situation.

# Example

WebAuthSubjectAuthType krb5
WebAuthTokenMaxTTL
How old a token that was should be recently created is valid for.
WebAuthTokenMaxTTL nnnn[s|m|h|d|w]
WebAuthTokenMaxTTL 300s
server config
virtual host

This directive sets how old tokens that must be considered recent can be before they are considered stale. It is used to help prevent tokens from being replayed, and to ignore those token if they occur in cookies, URLs, etc. This requires clocks between the web server and the WebKDC to be synchronized.

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

# Example

    # ten minute TTL
    WebAuthTokenMaxTTL 10m

WebAuthTrustAuthzIdentity
Whether to use the authorization identity as the authenticated user
WebAuthTrustAuthzIdentity on|off
WebAuthTrustAuthzIdentity off
server config
virtual host
directory
.htaccess

By default, WebAuth ignores any authorization identity sent by the WebKDC and uses the user's authenticated identity as the Apache identity (for authorization checks and logging) and for the REMOTE_USER environment variable. To allow the user (with the WebKDC's permission and vetting) to assert a different authorization identity than their authenticated identity, set this directive to `on`. This can be set or changed at any scope, including .htaccess files if AuthConfig overrides are allowed.

Even if this directive is left off (the default), the authorization identity (if present) is available in the WEBAUTH_AUTHZ_USER environment variable. However, if this directive is not turned on, the authorization identity won't be used for any purpose other than populating that environment variable.

If this directive is enabled, the authorization identity will be passed to Apache as the user's identity, just as if they'd authenticated as that user. That will affect any further authorization checks, group membership checks, or other modules that retrieve information based on the authenticated identity, such as LDAP modules.

Even if this directive is enabled, the WEBAUTH_USER environment variable will always be set to the authenticated identity, ignoring any authorization identity.

# Warning for WebAuthSubjectAuthType

The interaction between this directive and either WebAuthSubjectAuthType or WebAuthCred may be unexpected.

Setting WebAuthSubjectAuthType to `krb5` indicates that mod_webauth should not solely trust the WebKDC's assertion of identity and instead independently verify the authentication credentials of the user. However, there is no way to independently verify the authorization identity. Therefore, setting WebAuthSubjectAuthType to `krb5` tells mod_webauth to ignore the authorization identity. The `webkdc` subject auth type (the default) must be used to use this feature.

WebAuthCred can be used in combination with this directive, but all obtained credentials will be for the authentication identity, not for the authorization identity. There is currently no way to obtain credentials for the authorization identity.

# Warning for WebAuthForceLogin

Be aware that, with the typical WebLogin configuration, setting WebAuthForceLogin will make asserting an authorization identity impossible. Normally, WebLogin lets the user change the authorization identity after authentication, since only then does it know what possible authorization identities are permitted. But when WebAuthForceLogin is in effect, the authorization identity cannot be changed without repeating the authentication, which may effectively disable the option. If you are using authorization identities, consider using WebAuthRequireSessionFactor instead.

# Example

WebAuthTrustAuthzIdentity on

# Note on Logging

By default, the Apache access log includes, in the third field, the identity of the user accessing a page that requires authentication. This is the authorization identity: the identity stored in the REMOTE_USER environment variable and used for authorization checks.

When the WebAuthTrustAuthzIdentity directive is enabled, it may be useful to also log the authentication identity. The WebAuth module will log to the error log the authentication and authorization identities after the initial authentication to that server, but it can be hard to correlate that with access log entries.

There is a field in the access log that can be used for this purpose, although it requires a change to the default Apache log format. The second field in a standard access log entry is normally the remote connection identity as determined by the ident protocol. However, this protocol is obsolete and insecure, and this check is disabled by default, so in a typical Apache installation, this field is always empty (`-`). Existing log parsers understand this field, so it can be reused to store the authentication identity so that both identities can be logged.

To do this, change the second field of the Apache access log format from `%l` to `%{WEBAUTH_USER}e`. This will log the WebAuth authentication identity, if any, in the second field, and leave the second field as `-` if no authentication identity is established.

# Logging Example

    # Replace ident field with WebAuth authentication identity.
    LogFormat \
     "%h %{WEBAUTH_USER}e %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" \
     webauth_combined
    CustomLog /var/log/apache2/access.log webauth_combined

WebAuthUseCreds
Whether or not save credentials to the cache
WebAuthUseCreds on|off
WebAuthUseCreds off
directory

This directive controls whether or not any acquired credentials will actually be saved to the credential cache directory and made available as part of the current request. It should be used in conjunction with the WebAuthCred directive.

# Example

    <Location /myapp/command>
      WebAuthUseCreds on
    </Location>

WebAuthVarPrefix
Additional WebAuth-related environment variables to set
WebAuthVarPrefix string
WebAuthVarPrefix ""
directory
.htaccess

The WebAuth module sets various environment variables that are made available at the time of document or application serving. They are all prefixed by "WEBAUTH" (for instance WEBAUTH_USER), but some CGI apps (specifically the Oracle WRB) have expectations about and/or restrictions on the names of environment variables they can handle. Set this to a string you want prepended to the environment variables this module defines, and they will be set in addition to the standard "WEBAUTH" ones.

# Example

    <Location /myapp/>
      # this will cause both WEBAUTH_USER and HTTP_WEBAUTH_USER
      # environment variables to get set.
      WebAuthVarPrefix HTTP_
    </Location>

WebAuthWebKdcPrincipal
The Kerberos principal name of the WebKDC
WebAuthWebKdcPrincipal principal
(none)
server config
virtual host

This is the name of the Kerberos principal to use when communicating with the WebKDC. It used to request a service-token from the WebKDC.

# Note

This directive must be set.

# Example

    # if realm isn't specified, the default realm will be used
    WebAuthWebKdcPrincipal service/webkdc@stanford.edu

WebAuthWebKdcSSLCertCheck
Whether or not to perform SSL certificate checking on the WebKDC's certificate
WebAuthWebkdcSSLCertCheck on|off
on
server config
virtual host

This directive controls whether or not SSL certificate checking is performed on the certificate used by the WebKDC when mod_webauth communicates directly with the WebKDC.

# Note

Setting this directive to `off` opens a security hole and should only be used in development when the WebAuthWebKdcSSLCertFile directive cannot be used.

# Example

WebAuthWebKdcSSLCertCheck off
WebAuthWebKdcSSLCertFile
Name of the WebKDC's certificate file.
WebAuthWebkdcSSLCertFile path
(none)
server config
virtual host

This is the name of a file holding one or more certificates to verify the WebKDC's SSL Certificate with. This directive is only needed if you are using a self-signed certificate with your WebKDC, or a certificate signed by a certificate authority that isn't recognized. If you are using a self-signed certificate, you should copy that certificate (the file mentioned in the WebKDC's Apache SSLCertificateFile directive) to a local file, and point to that file with this directive.

If the path is not absolute, then it will be treated as being relative to `ServerRoot`.

# Note

This directive is only needed when the WebKDC is using a self-signed certificate . It is not needed if your WebAuth server is using a self-signed certificate.

# Example

WebAuthWebKdcSSLCertFile conf/webauth/webkdc.cert
WebAuthWebKdcURL
The URL used to contact the WebKDC when posting XML
WebAuthWebKdcURL url
(none)
server config
virtual host

This is the URL used to post XML requests to the WebKDC, and should use always SSL.

# Note

This directive must be set.

# Example

WebAuthWebKdcURL https://webkdc.stanford.edu/webkdc-service/