<-
Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_webauth

Available Languages:  en 

Description:Support for the WebAuth protocol
Status:External
Module Identifier:webauth_module
Source File:mod_webauth.c
Compatibility:Apache 2.0 and higher

Summary

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.

Directives

Topics

top

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

top

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.

top

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.

top

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
ccookie Session authentication via cookie
ddevice 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.
hhuman 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.
kKerberos Session authentication via Kerberos authentication
mmultifactor Session or initial authentication via multiple independent authentication factors (site-defined)
oOTP 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
ppassword Session or initial authentication via traditional password
rmrandom multifactorNo User has a random chance of being challenged for a second factor; frequency of challenges is site-defined
uunknown Session or initial authentication via an unknown method
xX.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
top

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

top

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.

top

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.

top

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.

top

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

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.

top

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

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.

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

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.

top

WebAuthAppTokenLifetime Directive

Description:Lifetime of app-tokens we create.
Syntax:WebAuthAppTokenLifetime nnnn[s|m|h|d|w]
Default:(lifetime of id-token returned from WebKDC)
Context:directory
Status:External
Module:mod_webauth

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
top

WebAuthAuthType Directive

Description:Additional AuthType name to support
Syntax:WebAuthAuthType StanfordAuth
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthCookiePath Directive

Description: Path scope of cookies set by the module
Syntax:WebAuthCookiePath scope
Default:/
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

WebAuthCred Directive

Description:Which credentials to acquire
Syntax:WebAuthCred type [service]
Default:(none)
Context:directory
Status:External
Module:mod_webauth

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

WebAuthCredCacheDir Directive

Description: Name of the directory containing cached credentials
Syntax:WebAuthCredCacheDir path
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthDebug Directive

Description:Turn on extra debugging in Apache error log
Syntax:WebAuthDebug on|off
Default:WebAuthDebug off
Context:server config, virtual host
Status:External
Module:mod_webauth

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
top

WebAuthDoLogout Directive

Description:Destroy all WebAuth-related cookies
Syntax:WebAuthDoLogout on|off
Default:WebAuthDoLogout off
Context:directory, .htaccess
Status:External
Module:mod_webauth

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.

top

WebAuthDontCache Directive

Description:Turn on expire header
Syntax:WebAuthDontCache on|off
Default:WebAuthDontCache off
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

See also

top

WebAuthExtraRedirect Directive

Description: Whether or not to do an extra redirect upon return from the WebKDC
Syntax:WebAuthExtraRedirect on|off
Default:WebAuthExtraRedirect on
Context:server config, virtual host, directory, .htaccess
Status:External
Module:mod_webauth

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.

top

WebAuthFailureURL Directive

Description: The URL browsers get redirected to when a fatal mod_webauth error occurs
Syntax:WebAuthFaliureURL url
Default:(none)
Context:directory
Status:External
Module:mod_webauth

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

top

WebAuthForceLogin Directive

Description: Forces interactive authentication when user is not authenticated
Syntax:WebAuthForceLogin on|off
Default:WebAuthForceLogin off
Context:directory
Status:External
Module:mod_webauth

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

WebAuthHttpOnly Directive

Description:Whether or not to set WebAuth cookies HttpOnly
Syntax:WebAuthHttpOnly on|off
Default:on
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthInactiveExpire Directive

Description: Expiration period for app tokens that haven't been used recently
Syntax:WebAuthInactiveExpire nnnn[s|m|h|d|w]
Default:(disabled)
Context:directory
Status:External
Module:mod_webauth

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
top

WebAuthKeyring Directive

Description:Name of the file containing the WebAuth keyring
Syntax:WebAuthKeyring path
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthKeyringAutoUpdate Directive

Description:Whether or not we auto-update the keyring file
Syntax:WebAuthKeyringAutoUpdate on|off
Default:WebAuthKeyringAutoUpdate on
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthKeyringKeyLifetime Directive

Description: Lifetime of keys in the keyring if we auto-update
Syntax:WebAuthAKeyringKeyLifetime nnnn[s|m|h|d|w]
Default:WebAuthKeyringKeyLifetime 30d
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthKeytab Directive

Description:Name of the Kerberos keytab file
Syntax:WebAuthKeytab path [principal]
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthLastUseUpdateInterval Directive

Description:How often to update the main webauth cookie
Syntax:WebAuthLastUseUpdateInterval nnnn[s|m|h|d|w]
Default:WebAuthLastUsedUpdateInterval 0
Context:directory
Status:External
Module:mod_webauth

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
top

WebAuthLoginCanceledURL Directive

Description:URL to return to if user cancels out of login
Syntax:WebAuthLoginCanceledURL url
Default:(none)
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

top

WebAuthLoginURL Directive

Description: The URL browsers get redirected to when the user is unauthenticated
Syntax:WebAuthLoginURL url
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthOptional Directive

Description: Whether or not to require the use to authenticate
Syntax:WebAuthOptional on|off
Default:off
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

top

WebAuthPostReturnURL Directive

Description: URL to return to after authenticating during a POST
Syntax:WebAuthPostReturnURL url
Default:(none)
Context:directory, .htaccess
Status:External
Module:mod_webauth

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/
top

WebAuthRequireInitialFactor Directive

Description:Required factors for initial authentication
Syntax: WebAuthRequireInitialFactor factor [factor ...]
Default:(none)
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

top

WebAuthRequireLOA Directive

Description:Required level of assurance for authentication
Syntax:WebAuthRequireLOA loa
Default:0
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

top

WebAuthRequireSessionFactor Directive

Description:Required factors for session authentication
Syntax: WebAuthRequireSessionFactor factor [factor ...]
Default:(none)
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

top

WebAuthRequireSSL Directive

Description: Whether SSL is required to access a WebAuth-protected resource
Syntax:WebAuthRequireSSL on|off
Default:WebAuthRequireSSL on
Context:server config, virtual host
Status:External
Module:mod_webauth

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

WebAuthReturnURL Directive

Description:URL to return to after authenticating
Syntax:WebAuthReturnURL url
Default:(url user originally requested)
Context:directory, .htaccess
Status:External
Module:mod_webauth

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/
top

WebAuthServiceTokenCache Directive

Description:Name of the service-token cache file.
Syntax:WebAuthServiceTokenCache path
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthSSLRedirect Directive

Description: Redirect to https when accessing a WebAuth-protected page via http
Syntax:WebAuthSSLRedirect on|off
Default:WebAuthSSLRedirect off
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthSSLRedirectPort Directive

Description:port to use when redirecting the user to https
Syntax:WebAuthSSLRedirectPort port
Default:WebAuthSSLRedirectPort 443
Context:server config, virtual host
Status:External
Module:mod_webauth

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
top

WebAuthSSLReturn Directive

Description:Sets the return URL to be https
Syntax:WebAuthSSLReturn on|off
Default:WebAuthSSLReturn off
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

WebAuthStripURL Directive

Description: Whether or not to strip WebAuth information from the internal URL
Syntax:WebAuthStripURL on|off
Default:on
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthSubjectAuthType Directive

Description: Type of subject authenticator the WebKDC will use in the returned id-token
Syntax:WebAuthSubjectAuthType type
Default:WebAuthSubjectAuthType webkdc
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthTokenMaxTTL Directive

Description: How old a token that was should be recently created is valid for.
Syntax:WebAuthTokenMaxTTL nnnn[s|m|h|d|w]
Default:WebAuthTokenMaxTTL 300s
Context:server config, virtual host
Status:External
Module:mod_webauth

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
top

WebAuthTrustAuthzIdentity Directive

Description: Whether to use the authorization identity as the authenticated user
Syntax:WebAuthTrustAuthzIdentity on|off
Default:WebAuthTrustAuthzIdentity off
Context:server config, virtual host, directory, .htaccess
Status:External
Module:mod_webauth

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
top

WebAuthUseCreds Directive

Description:Whether or not save credentials to the cache
Syntax:WebAuthUseCreds on|off
Default:WebAuthUseCreds off
Context:directory
Status:External
Module:mod_webauth

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

WebAuthVarPrefix Directive

Description:Additional WebAuth-related environment variables to set
Syntax:WebAuthVarPrefix string
Default:WebAuthVarPrefix ""
Context:directory, .htaccess
Status:External
Module:mod_webauth

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

WebAuthWebKdcPrincipal Directive

Description:The Kerberos principal name of the WebKDC
Syntax:WebAuthWebKdcPrincipal principal
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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
top

WebAuthWebKdcSSLCertCheck Directive

Description: Whether or not to perform SSL certificate checking on the WebKDC's certificate
Syntax:WebAuthWebkdcSSLCertCheck on|off
Default:on
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthWebKdcSSLCertFile Directive

Description:Name of the WebKDC's certificate file.
Syntax:WebAuthWebkdcSSLCertFile path
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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

top

WebAuthWebKdcURL Directive

Description: The URL used to contact the WebKDC when posting XML
Syntax:WebAuthWebKdcURL url
Default:(none)
Context:server config, virtual host
Status:External
Module:mod_webauth

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/

Available Languages:  en 

top