Apache HTTP Server Version 2.0
Apache HTTP Server Version 2.0
Available Languages: en
| Description: | Support for the WebAuth V3 protocol |
|---|---|
| Status: | |
| Module Identifier: | webauth_module |
| Source File: | mod_webauth.c |
This module implements the authentication component of a WebAuth V3 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.
WebAuthAppTokenLifetime WebAuthAuthType WebAuthCred WebAuthCredCacheDir WebAuthDebug WebAuthDoLogout WebAuthDontCache WebAuthExtraRedirect WebAuthFailureURL WebAuthForceLogin WebAuthInactiveExpire WebAuthKeyring WebAuthKeyringAutoUpdate WebAuthKeyringKeyLifetime WebAuthKeytab WebAuthLastUseUpdateInterval WebAuthLoginCanceledURL WebAuthLoginURL WebAuthPostReturnURL WebAuthReturnURL WebAuthServiceTokenCache WebAuthSSLRedirect WebAuthSSLRedirectPort WebAuthSSLReturn WebAuthStripURL WebAuthSubjectAuthType WebAuthTokenMaxTTL WebAuthUseCreds WebAuthVarPrefix WebAuthWebKdcPrincipal WebAuthWebKdcSSLCertCheck WebAuthWebKdcSSLCertFile WebAuthWebKdcURL Minimal Config File Using WebAuth Authentication Environment Variables Using WebAuth with Proxy Servers Perl Integration PHP 4.x Integration Java/Tomcat/mod_jk Integration Requesting Credentials Debugging mod_webauth Setting up load-balanced WebAuth servers
The following example shows the minimum config file required to configure mod_webauth.
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).
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.
<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.
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, request Kerberos V5 credentials will result in the KRB5CCNAME environment variable being set.
| Variable Name: | Description: |
|---|---|
WEBAUTH_USER |
Name of the WebAuth authenticated user |
WEBAUTH_TOKEN_CREATION |
When the token was created |
WEBAUTH_TOKEN_EXPIRATION |
When the token will expire. Note: 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 |
REMOTE_USER |
Name of the WebAuth authenticated user |
AUTH_TYPE |
Will be set to WebAuth |
REMOTE_USER=schemers
AUTH_TYPE=WebAuth
WEBAUTH_USER=schemers
WEBAUTH_TOKEN_CREATION=103872393
WEBAUTH_TOKEN_EXPIRATION=1038759389
WEBAUTH_TOKEN_LASTUSED=103872393
When checking for the authenticated username, use WEBAUTH_USER if you want to be sure that the authentication happened via WebAuth (or check AUTH_TYPE to be sure that it is set to WebAuth). If you want your application to be able to support any Apache authentication mechanism, use REMOTE_USER, as this is the standard inside Apache. Most web applications should use REMOTE_USER by preference so that they are independent of the authentication system used.
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:
<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.
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.
/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.)
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:
<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:
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.
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:
<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:
$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.
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:
# 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.
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.
You will also need to explicitly turn off Tomcat authentication in the
<Connector> definition in the Tomcat
server.xml file. For example:
<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
port="8009" minProcessors="5" maxProcessors="75"
tomcatAuthentication="false"
acceptCount="10" debug="0"/>
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 V5 credentials.
# 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>
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.
webauth
handler after you have mod_webauth configured correctly.
# WebAuthDebug must be on WebAuthDebug on <Location /webauth-status> SetHandler webauth Order allow,deny Allow from all </Location>
WebAuth V3 was designed so that it would be fairly easy to setup multiple WebAuth servers for load balancing and redundancy. There are two pieces of information that need to be shared between WebAuth servers in order to achieve this:
All the files 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. These files should only be updated on the master and pushed manually to the slaves.
The Kerberos keytab file is specified using the WebAuthKeyTab directive. This is a standard Kerberos V5 keytab file containing the principal/key used by WebAuth servers to initially communicate with the WebKDC.
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:
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:
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:
$ wa_keyring -f ./keyring list Path: ./keyring id Created Valid after Fingerprint 0 02/13/2003 12:43:25 02/13/2003 12:43:25 664b48642f741ae343ef5ea46a8768e8 1 03/12/2003 16:21:57 03/12/2003 16:21:57 7c4971e760f75525bba277a308c092c0 $ wa_keyring -f ./keyring remove 0
Or it can be done automatically, using the gc command:
# 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:
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:
# 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.
| 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: | |
| 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.
# create an app-token valid for 2 hours
WebAuthAppTokenLifetime 2h
| Description: | Additional AuthType name to support |
|---|---|
| Syntax: | WebAuthAuthType authtype |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| Module: | mod_webauth |
This sets an additional AuthType name that will
be treated the same as WebAuth when used with the
AuthType directive.
This directive exists to help people transition from other
AuthType names to WebAuth. It is recommended
that people transition over to using only WebAuth as soon
as possible.
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.
WebAuthAuthType StanfordAuth
| Description: | Which credentials to acquire |
|---|---|
| Syntax: | WebAuthCred type [service] |
| Default: | (none) |
| Context: | directory |
| Status: | |
| 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.
# 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>
| Description: | Name of the directory containing cached credentials |
|---|---|
| Syntax: | WebAuthCredCacheDir path |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| 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.
This directive must be set if the WebAuthCred and WebAuthUseCreds directives are used.
WebAuthCredCacheDir conf/webauth/credcache
| Description: | Turn on extra debugging in Apache error_log |
|---|---|
| Syntax: | WebAuthDebug on|off |
| Default: | WebAuthDebug off |
| Context: | server config, virtual host |
| Status: | |
| Module: | mod_webauth |
Whether or not to do extra debugging in error_log. You should
also set Apache's LogLevel to debug as
well.
WebAuthDebug on
LogLevel debug
| Description: | Destroy all WebAuth-related cookies |
|---|---|
| Syntax: | WebAuthDoLogout on|off |
| Default: | WebAuthDoLogout off |
| Context: | directory |
| Status: | |
| 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.
<Location /myapp/logout>
WebAuthDoLogout on
</Location>
| Description: | Turn on expire header |
|---|---|
| Syntax: | WebAuthDontCache on|off |
| Default: | WebAuthDontCache off |
| Context: | directory, .htaccess |
| Status: | |
| 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.
WebAuthDontCache on
| 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: | |
| 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).
<Location /myapp/>
WebAuthExtraRedirect off
...
</Location>
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.
| Description: | The URL browsers get redirected to when a fatal mod_webauth error occurs |
|---|---|
| Syntax: | WebAuthFaliureURL url |
| Default: | (none) |
| Context: | directory |
| Status: | |
| 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.
WebAuthFailureURL /app/sorry.html
| Description: | Forces username/password prompt when user is not authenticated |
|---|---|
| Syntax: | WebAuthForceLogin on|off |
| Default: | WebAuthForceLogin off |
| Context: | directory |
| Status: | |
| Module: | mod_webauth |
This directive controls whether or not a user will be prompted for a username/password if they need to be redirected to the WebKDC for authentication.
# 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>
| Description: | Expires app-tokens that haven't been used recently |
|---|---|
| Syntax: | WebAuthInactiveExpire nnnn[s|m|h|d|w] |
| Default: | (disabled) |
| Context: | directory |
| Status: | |
| 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 the WebAuthForceLogin directive, 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.
# 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
| Description: | Name of the file containing the webauth keyring |
|---|---|
| Syntax: | WebAuthKeyring path |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| 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).
The keyring file gets read once per child and cached for the duration of a child.
If the path
is not absolute, then it will be treated as being relative to ServerRoot.
This directive must be set.
WebAuthKeyRing conf/webauth/keyring
| Description: | Whether or not we auto-update the keyring file |
|---|---|
| Syntax: | WebAuthKeyringAutoUpdate on|off |
| Default: | WebAuthKeyringAutoUpdate on |
| Context: | server config, virtual host |
| Status: | |
| Module: | mod_webauth |
This directive controls whether or not we auto-update the keyring file. This includes creating it if it doesn't exist, and generating a new key before the old key expires, and periodically garbage collecting old keys. Note that auto updating only occurs on server startup and restarts.
This directive should be turned off if multiple servers are sharing the same keyring file so the keyring file can be manually updated. That too will eventually be automated.
WebAuthKeyringAutoUdpate off
| 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: | |
| 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.
WebAuthKeyringKeyLifetime 60d
| Description: | Name of the Kerberos V5 keytab file |
|---|---|
| Syntax: | WebAuthKeytab path [principal] |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| Module: | mod_webauth |
This is the name of the Kerberos V5 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.
This directive must be set.
WebAuthKeytab conf/webauth/keytab webauth/slapshot.stanford.edu
| Description: | How often to update the main webauth cookie |
|---|---|
| Syntax: | WebAuthLastUseUpdateInterval nnnn[s|m|h|d|w] |
| Default: | WebAuthLastUsedUpdateInterval 0 |
| Context: | directory |
| Status: | |
| 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.
# 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
| Description: | URL to return to if user cancels out of login |
|---|---|
| Syntax: | WebAuthLoginCanceledURL url |
| Default: | (none) |
| Context: | directory, .htaccess |
| Status: | |
| 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.
If this directive is not set and the user hits the cancel button, they will be taken to a standard "login canceled" page at the WebKDC.
WebAuthLoginCanceledURL /nonwebauth/info.html
| Description: | The URL browsers get redirected to when the user is unauthenticated |
|---|---|
| Syntax: | WebAuthLoginURL url |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| 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.
This directive must be set.
WebAuthLoginURL https://webkdc.stanford.edu/login/
| Description: | URL to return to after authenticating during a POST |
|---|---|
| Syntax: | WebAuthPostReturnURL url |
| Default: | (none) |
| Context: | directory, .htaccess |
| Status: | |
| 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.
# if unauthenticated when accessing a URL via a POST,
# authenticate and return to front-page
WebAuthPostReturnURL /myapp/
| Description: | URL to return to after authenticating |
|---|---|
| Syntax: | WebAuthReturnURL url |
| Default: | (url user originally requested) |
| Context: | directory, .htaccess |
| Status: | |
| 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.
# if unauthenticated when accessing a URL, authenticate
# and return to front-page
WebAuthReturnURL /myapp/
| Description: | Name of the service-token cache file. |
|---|---|
| Syntax: | WebAuthServiceTokenCache path |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| 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.
This directive must be set.
WebAuthServiceTokenCache conf/webauth/service_token_cache
| 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: | |
| 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.
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.
WebAuthSSLRedirect on
| Description: | port to use when redirecting the user to https |
|---|---|
| Syntax: | WebAuthSSLRedirectPort port |
| Default: | WebAuthSSLRedirectPort 443 |
| Context: | server config, virtual host |
| Status: | |
| 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.
WebAuthSSLRedirect on
WebAuthSSLRedirectPort 8443
| Description: | Sets the return URL to be https |
|---|---|
| Syntax: | WebAuthSSLReturn on|off |
| Default: | WebAuthSSLReturn off |
| Context: | directory |
| Status: | |
| 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.
<Location /myapp/>
AuthType WebAuth
Require valid-user
WebAuthSSLReturn on
</Location>
| Description: | Whether or not to strip WebAuth information from the internal URL |
|---|---|
| Syntax: | WebAuthStripURL on|off |
| Default: | on |
| Context: | server config, virtual host |
| Status: | |
| 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.
WebAuthStripURL off
| 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: | |
| 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:
krb5
When this type of subject authenticator is used, the WebKDC will use
the user's Kerberos V5 credentials to make a krb5_mk_req
call, using the requesting web server's Kerberos V5 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 basically 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.
The downside to using this option is that returned id-token will
be about 500 bytes longer then when using a type of webkdc.
Specifying this also requires that WebAuthKeytab be set. (FIXME: it is already always required for obtaining a service-token, though it will probably become optional at some point).
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.
WebAuthSubjectAuthType krb5
| 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: | |
| 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.
# ten minute TTL
WebAuthTokenMaxTTL 10m
| Description: | Whether or not save credentials to the cache |
|---|---|
| Syntax: | WebAuthUseCreds on|off |
| Default: | WebAuthUseCreds off |
| Context: | directory |
| Status: | |
| 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.
<Location /myapp/command>
WebAuthUseCreds on
</Location>
| Description: | Additional webauth-related environment variables to set |
|---|---|
| Syntax: | WebAuthVarPrefix string |
| Default: | WebAuthVarPrefix "" |
| Context: | directory, .htaccess |
| Status: | |
| 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.
<Location /myapp/>
# this will cause both WEBAUTH_USER and HTTP_WEBAUTH_USER
# environment variables to get set.
WebAuthVarPrefix HTTP_
</Location>
| Description: | The Kerberos V5 principal name of the WebKDC |
|---|---|
| Syntax: | WebAuthWebKdcPrincipal principal |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| Module: | mod_webauth |
This is the name of the Kerberos V5 Principal to use when communicating with the WebKDC. It used to request a service-token from the WebKDC.
This directive must be set.
# if realm isn't specified, the default realm will be used
WebAuthWebKdcPrincipal service/webkdc@stanford.edu
| 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: | |
| 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.
Setting this directive to off opens a security hole
and should only be used in development when the
WebAuthWebKdcSSLCertFile
directive cannot be used.
WebAuthWebKdcSSLCertCheck off
| Description: | Name of the WebKDC's certificate file. |
|---|---|
| Syntax: | WebAuthWebkdcSSLCertFile path |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| 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. 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.
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
WebAuthWebKdcSSLCertFile conf/webauth/webkdc.cert
| Description: | The URL used to contact the WebKDC when posting XML. |
|---|---|
| Syntax: | WebAuthWebKdcURL url |
| Default: | (none) |
| Context: | server config, virtual host |
| Status: | |
| Module: | mod_webauth |
This is the URL used to post XML requests to the WebKDC, and should use always SSL.
This directive must be set.
WebAuthWebKdcURL https://webkdc.stanford.edu/webkdc-service/
Available Languages: en