Apache Module mod_webauth

WebAuthAppTokenLifetime Directive

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

WebAuthAuthType Directive

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.

WebAuthCookiePath Directive

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.

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

WebAuthCred Directive

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>

WebAuthCredCacheDir Directive

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.

WebAuthDebug Directive

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

WebAuthDebug on
LogLevel debug

WebAuthDoLogout Directive

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>

WebAuthDontCache Directive

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

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

See also

• mod_expires

WebAuthExtraRedirect Directive

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>

WebAuthFailureURL Directive

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.

WebAuthForceLogin Directive

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.

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

WebAuthHttpOnly Directive

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.

WebAuthInactiveExpire Directive

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.

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

WebAuthKeyring Directive

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.

WebAuthKeyringAutoUpdate Directive

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

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

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

WebAuthKeyringKeyLifetime Directive

This directive controls how long keys we automatically create for the keyring are valid. Keys will be valid from the time they are created until the lifetime is reached. 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.

WebAuthKeytab Directive

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.

WebAuthLastUseUpdateInterval Directive

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

WebAuthLoginCanceledURL Directive

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.

WebAuthLoginURL Directive

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.

WebAuthOptional Directive

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.

WebAuthPostReturnURL Directive

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/

WebAuthRequireInitialFactor Directive

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.

WebAuthRequireLOA Directive

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.

WebAuthRequireSessionFactor Directive

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.

WebAuthRequireSSL Directive

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.

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

WebAuthReturnURL Directive

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/

WebAuthServiceTokenCache Directive

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.

WebAuthSSLRedirect Directive

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.

WebAuthSSLRedirectPort Directive

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

WebAuthSSLReturn Directive

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.

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

WebAuthStripURL Directive

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.

WebAuthSubjectAuthType Directive

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.

WebAuthTokenMaxTTL Directive

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

WebAuthTrustAuthzIdentity Directive

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.

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

WebAuthUseCreds Directive

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>

WebAuthVarPrefix Directive

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>

WebAuthWebKdcPrincipal Directive

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.

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

WebAuthWebKdcSSLCertCheck Directive

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.

WebAuthWebKdcSSLCertFile Directive

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.

WebAuthWebKdcURL Directive

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