=============================================================== University of Cambridge Web Authentication System (UcamWebauth) Apache Authentication Agent (mod_ucam_webauth) Reference =============================================================== 1. Introduction 2. Configuration 2.1. Security 2.2. Configuration Directives 2.3. Logout page 2.4. Custom Error Pages 3. Authentication Information 4. Error Messages 1. Introduction =============== This document contains reference information about University of Cambridge Web Authentication System (UcamWebauth) Apache authentication module (mod_ucam_webauth). Instructions for building and installing the software are available in the INSTALL file. This module allows Apache to use UcamWebauth to identify users. Within the University, such a system is provided by Raven: http://raven.cam.ac.uk/. mod_ucam_webauth's operation is quite complex (see other UcamWebauth documentation) but a common sequence goes: 1) An initial request for a protected document causes mod_ucam_webauth to redirect the user's browser to a central authentication server 2) The authentication server and the user interact to establish the user's identity. This normally involves the user providing a user-id and password over a secure connection. The authentication server may set a session cookie so that it can respond to future authentication requests without needing to ask for the password again. 3) The central server redirects the user to the URL the user originally requested, including in the URL a cryptographically-signed 'response' containing the user's identity and other information. 4) mod_ucam_webauth intercepts this response and validates it. If this validation succeeds, mod_ucam_webauth sets a local session cookie containing the user's identity. 5) The user's browser is then redirected to the original URL yet again, this time without the response message. This request, and all subsequent ones for URLs that are similarly protected, are processed based on the information from the session cookie. The use of cookies may alarm some users. Sites that use mod_ucam_webauth should include a note about the local session cookie in their privacy policy or other suitable document. The cookie is set with no expiry date, which will prevent standards-compliant browsers from storing it on disk and will cause them to delete it at the end of the browser session. It is also set by default so that it will only be returned to the originating site. Sites can customise some of the behaviour of the session cookie - see '2.1 Configuration Directives' below. Because of the way that mod_ucam_webauth is implemented, if a redirect to the authentication server is triggered by an HTTP POST request then any parameters submitted along with the POST request will be lost. This is particularly annoying if you e.g. submit a carefully constructed message to a bulletin board only to discover that your session cookie has expired while you were composing the message. A warning message is logged to the error log if a redirect is required when responding to a POST request. mod_ucam_webauth only identifies people ('authentication') and leaves to other modules the task of making decisions based on that identity ('authorisation'). Apache includes a 'Require' directive which can limit access to particular resources to * anyone who can authenticate (e.g. 'Require valid-user') * people with one of a set of ids (e.g. 'Require user spqr fph1') * members of an separately defined group (e.g. 'AuthGroupFile /web/groups' followed by 'Require group admin'). In Apache 1.3 and 2.0, this functionality is provided by the mod_auth module. In Apache 2.2 it is provided by mod_authz_user, assisted by mod_authz_groupfile if using group files. These modules must be loaded if their facilities are used. The misleading error message "couldn't check access. No groups file?" suggests that one or more of the required modules are missing. See the Apache documentation for the 'Require' and 'AuthGroupFile' directives, and for general information about mod_auth, mod_authz_user and mod_authz_groupfile. In general, authorisation under mod_ucam_webauth works just as it does with any other Apache authentication method. Other modules are available, either in the standard Apache distribution or otherwise, that perform authorisation in other ways (e.g. mod_auth_dbm or mod_authz_dbm stores group information in DBM files). Some of these work with mod_ucam_webauth. However some don't becasue they work by combining their 'authentication' and 'authorisation' phases in such a way that one can't be used without the other. 2. Configuration ================ If the module has been built as a dynamic shared objects then it must first be loaded into Apache. Your distribution may have its own way of managing modules (see INSTALL.Platforms) but a default Apache installation would require a 'LoadModule' directive such as: LoadModule ucam_webauth_module modules/mod_ucam_webauth.so in the Apache configuration file, replacing 'modules/mod_ucam_webauth.so' if necessary with the path to the file containing the module, relative to ServerRoot if it doesn't start '/'. This is not necessary if the module has been statically linked into the httpd program. Under Apache 1.3 some configurations use 'ClearModuleList' followed by 'AddModule' directives to ensure that modules are used in a fixed order - if mod_ucam_webauth is loaded before 'ClearModuleList' then AddModule mod_ucam_webauth.c will also be required somewhere. mod_ucam_webauth does not depend on load order. AddModule is not used in Apache 2.0 or 2.2. The minimum configuration required to restrict access to resources in a particular directory to anybody with a Ucam-WebAuth login is, e.g. AACookieKey "some random string" AuthType Ucam-WebAuth Require valid-user An alternative simple configuration will allow access to the resources to users with a Ucam-WebAuth login or to client computers with hostnames ending .cam.ac.uk, but not otherwise: AACookieKey "some random string" Order allow,deny Allow from .cam.ac.uk AuthType Ucam-WebAuth Require valid-user Satisfy any In these examples the resources to be protected are selected by a directive; resources specified by or directives can also be protected in the same way. 'AuthType' must be set to 'Ucam-WebAuth'. A 'Require' directive must appear before authentication will take place. See standard Apache documentation for more details of the 'Order', 'Allow', 'Require', and 'Satisfy' directives. The AACookieKey directive is required, though it can appear either outside the block, in which case it provides a default for the entire server, or inside. It provides data used to sign and verify the session cookie, providing detection of any tampering. There is no default for this directive. 2.1. Security ------------- AACookieKey, and AAHeaderKey if used (see below), must be set to some random string and the value must be protected, since with knowledge of the key an attacker can forge authentication. Apache configuration files are often readable by any user of the system hosting the web server so it is a good idea to put the AACookieKey directive in a suitably protected file of its own and then use an Include directive to incorporate it in the main configuration file. Under Unix this file need only readable by the user used to start Apache, commonly root. It may also be necessary to disable the standard mod_info module since this can be use to display the Apache configuration and this will include the values assigned to AACookieKey and AAHeaderKey. Note that if mod_info is loaded into the server then anyone with write access to the main configuration file, or with the ability to create or modify an htaccess file allowing at least 'options FileInfo', can always arrange to access mod_info information. See mod_info documentation for further information. Authentication response messages are submitted to mod_ucam_webauth as the query component of URLs. In most common configurations these URLs, complete with the authentication response, will be logged to the web server access log. Anyone with real-time access to these log could use this information to replay an authentication response and so impersonate a recently logged-in user. Near real-time access is required because authentication response messages are subject to a short timeout (set by AAResponseTimeout and AAClockSkew). To avoid this exposure it should be sufficient to restrict access to logfiles to server administrators (which is good practice anyway). Alternatively the standard LogFormat or CustomLog directives could be used to suppress the logging of URL query components. Similar considerations apply to the possibility of authentication response messages or cookies being intercepted as they travel over the network. If this is considered to be a threat then the only realistic approach is to ensure that authentication only happens over SSL. 2.2. Configuration Directives ----------------------------- Apart from AACookieKey, the configuration directives specific to the module module are optional. However if the server's clock is not NTP synchronised then AAClockSkew will also need to be set. All directive values need to be quoted if they contain spaces. All directives can appear in the main server configuration or in , , and blocks, and in .htaccess files if 'AllowOverride AuthConfig' is in effect. AAAuthService Syntax: AAAuthService Default: AAAuthService https://raven.cam.ac.uk/auth/authenticate.html Context: all Override: AuthConfig Module: mod_ucam_webauth The full URL for the authentication service to be used. AALogoutService Syntax: AALogoutService Default: AALogoutService https://raven.cam.ac.uk/auth/logout.html Context: all Override: AuthConfig Module: mod_ucam_webauth The full URL for the logout page on the authentication service in use. AADescription Syntax: AADescription Context: all Override: AuthConfig Module: mod_ucam_webauth A text description of the resource that is requesting authentication. This may be displayed to the user by the authentication service. It is restricted to printable ASCII characters (0x20 - 0x7e) though it may contain HTML entities to represent other characters. The characters '<' and '>' will be converted into HTML entities before being sent to the browser and so this text can not contain HTML markup. AAResponseTimeout Syntax: AAResponseTimeout Default: AAResponseTimeout 20 Context: all Override: AuthConfig Module: mod_ucam_webauth Responses from the authentication service are time-stamped. This parameter sets the length of time for which these responses are considered valid. AAClockSkew Syntax: AAClockSkew Default: AAClockSkew 0 Context: all Override: AuthConfig Module: mod_ucam_webauth Interpretation of AAResponseTimeout is difficult if the clocks on the server running this handler and on the authentication service are out of step. Web servers should use NTP to synchronise their clocks, but if this one don't then this parameter MUST be set to the maximum possible difference between them. Error messages including the text 'local clock incorrect?' are likely if this parameter is not used on a server that needs it. AAKeyDir Syntax: AAKeyDir Default: AAKeyDir conf/webauth_keys Context: all Override: AuthConfig Module: mod_ucam_webauth The name of a directory containing the public key(s) required to validate authentication service responses. If this name does not start with '/' then it is interpreted relative to ServerRoot. AAMaxSessionLife Syntax: AAMaxSessionLife Default: AAMaxSessionLife 7200 Context: all Override: AuthConfig Module: mod_ucam_webauth The period of time for which an established session will be valid. This may be reduced if the authentication service response includes a shorter 'life' parameter (but see AAIgnoreResponseLife below). Once a session ceases to be valid, users will be referred to the authentication service to re-authenticate. Note that this does NOT define an expiry time for the session cookie - session cookies are always set without an expiry time, causing them to expire when the browser session finishes. 7200 seconds is 2 hours. AAInactiveTimeout Syntax: AAInactiveTimeout Default: AAInactiveTimeout 0 Context: all Override: AuthConfig Module: mod_ucam_webauth The length of time after which an inactive session can be assumed to have expired. Inactivity tracking is rather approximate thanks to various forms of caching. In particular, revisiting a page that hasn't change since you last visited it may not count as activity - setting AACacheControl to 'paranoid' may help with this, at the expense of increased network traffic and delays. If set to 0 this feature is disabled. Disabling the feature when not required provides a minor efficiency gain. AATimeoutMsg Syntax: AATimeoutMsg Default: AATimeoutMsg "your session on the site has expired" Context: all Override: AuthConfig Module: mod_ucam_webauth A re-authentication by the authentication service will be triggered when a session expires. This option sets a text string which is sent to the authentication service to explain to the user why they are being asked to authenticate again. HTML markup is suppressed as for AADescription above. Setting a value of 'none' (case insensitive) will restore the default action. AACacheControl Syntax: AACacheControl Off|On|Paranoid Default: AACacheControl On Context: all Override: AuthConfig Module: mod_ucam_webauth Caches, both those in browsers and shared proxy caches, can cause problems for cookie-based authentication systems. This option controls what the module does to work around this. It has three possible settings: Off: No additional headers are sent. On: Headers are automatically sent that should disable most shared caching. Paranoid: Almost everything possible is done to discourage re-use of cached content. This will increase server load, network traffic and delays experienced by users. Shared caches will not cause problems if all authenticated traffic is over https, in which case it is generally safe to set this directive to 'off'. Indeed it can be a god idea to do so to avoid problems with downloads when using Internet Explorer (see for example http://support.microsoft.com/kb/812935). AACookieKey Syntax: AACookieKey "text" Context: all Override: AuthConfig Module: mod_ucam_webauth A random key used to protect session cookies from tampering. Any reasonably unpredictable string (for example an md5sum taken from a rapidly changing logfile) will be satisfactory. This key must be the same for all uses of the module that will receive the same session cookies (see AACookieName, AACookiePath, AACookieDomain below). This parameter has no default and must be set. The key must not disclosed, since with knowledge of the key an attacker can forge authentication. For preference, AACookieKey should be placed in a file that is only readable by the user used to start Apache, commonly root. One way to achieve this, while leaving the main configuration file mainly readable, would be to put the AACookieKey directive in a file only readable by root (or whoever) that is incorporated into the main configuration using the 'Include' directive. It may also be necessary to disable the standard mod_info module since this can be use to display the Apache configuration and this will include the value assigned to AACookieKey. AACookieName Syntax: AACookieName Default: AACookieName Ucam-WebAuth-Session Context: all Override: AuthConfig Module: mod_ucam_webauth The name used for the session cookie. For servers running on non-default ports the string '-' is appended to this name, and when used for access to resources over https the string '-S' is also appended.. AACookiePath Syntax: AACookiePath Default: AACookiePath / Context: all Override: AuthConfig Module: mod_ucam_webauth The 'Path' attribute for the session_cookie. The default should cause the cookie to be returned in response to all requests for this server. Be sure to set this path so that it actually includes all the URLs being protected. For example AACookieKey foobar AACookiePath /protected/ will cause problems when a browser tries to access http:///protected since authentication will be required but the relevant cookie will never be returned. Note that an .htaccess file and a Directory block even with a trailing '/' seem to behave as for a Location block with a path without the trailing '/'. The module checks for requests with URLs that are out of the scope of the corresponding cookie and returns and logs an error if this occurs. AACookieDomain Syntax: AACookieDomain Default: AACookieDomain '' Context: all Override: AuthConfig Module: mod_ucam_webauth The 'Domain' attribute for the session cookie. The default will result in the cookie being returned only to the server using the module. Be aware that some people may treat with suspicion cookies with domain attributes that are wider than the host setting the cookie, and that cookies with very short domains (less than 2 or 3 components) may be silently ignored by browsers. AAForceInteract Syntax: AAForceInteract Off|On Default: AAForceInteract Off Context: all Override: AuthConfig Module: mod_ucam_webauth If set, users will be required to enter their passwords every time they are referred to the authentication service and will not be able to take advantage of the 'single sign-on' features. Setting this may be appropriate for some applications that have higher than normal security requirements, but doing so will significantly reduce user convenience. AAFail Syntax: AAFail Off|On Default: AAFail Off Context: all Override: AuthConfig Module: mod_ucam_webauth If enabled, all requests sent to the authentication service will indicate that the authentication service itself should report any errors that it encounters, rather than returning an error indication to the module. Note however that even with this parameter set errors may be detected by this module that will cause it to return errors itself. AACancelMsg Syntax: AACancelMsg Context: all Override: AuthConfig Module: mod_ucam_webauth If set, this identifies the message that will be displayed on the user's browser if the user cancelled the authentication (assuming that AAAFail is not set). If unset or 'none' (case insensitive), a standard message will be displayed. can be a text message (enclosed in quotes), or a partial or full URL. See the Custom Error Pages section below. AANoCookieMsg Syntax: AANoCookieMsg Context: all Override: AuthConfig Module: mod_ucam_webauth If set, this identifies the message that will be displayed on the user's browser if the browser does not appear to be accepting the session cookie (without which this module won't work). If unset or 'none' (case insensitive), a standard message will be displayed. can be a text message (enclosed in quotes), or a partial or full URL. See the Custom Error Pages section. AALogoutMsg Syntax: AALogoutMsg Context: all Override: AuthConfig Module: mod_ucam_webauth If set, this identifies the message that will be displayed on the user's browser when they access a logout page. If unset or 'none' (case insensitive), a standard message will be displayed. can be a text message (enclosed in quotes), or a partial or full URL. See the Logout page section below. AAAlwaysDecode Syntax: AAAlwaysDecode Off|On Default: AAAlwaysDecode Off Context: all Override: AuthConfig Module: mod_ucam_webauth If this directive is in force for a particular URL then the module will always attempt to decode the session cookie and store the results in the environment (see below) even if authentication isn't actively required. This could be useful for a site that does not want to require authentication for some information but which does want to provide customisation if the user is already identified (presumably as a result of accessing something else), or for a site that wanted to mediate all accesses through a single point (such as page.php) but wanted to impose its own authorisation decisions on who sees what. For example AACookieKey AAAlwaysDecode On AuthType WebAuth Require valid-user would allow everyone to see anything other than login.html. Visiting login.html would trigger authentication. Content elsewhere in the site (foo.cgi, foo.php, foo.ssi, etc) can check if the user is already authenticated, and if so who they are, by inspecting the REMOTE_USER environment variable. AAHeaders Syntax: AAHeaders all | none | item[ item...] Default AAHeaders none Context: all Override: AuthConfig Module: mod_ucam_webauth Following successful authentication, the module can make various items of authentication information (see 3. Authentication Information below for details) available as if they had appeared in the HTTP headers of the request being processed. While of limited use on a single server (identical information is available in environment variables) this functionality can be useful where authentication is performed on one machine and Apache mod_proxy functionality is then used to forward the request to a different machine. In this case the new headers will be forwarded with the request. This represents one way in which the authentication provided by mod_ucam_webauth can be exploited on a web server other than Apache. This directive should either be followed by a space separated list of the authentication items (see below) to include as headers, or by the word 'all' to include all possible items, or by the word 'none' to include none. The arguments to the directive are interpreted case-insensitively. Each use of the directive sets the entire list of items to include - individual items are not inherited and the directive does not support the '+/-' syntax used by standard directives like Options. For each item requested, a header will be added to the current request. Its name will be formed from the item name by appending 'X-AA' - for example the directive 'AAHeaders principal' will add a header called 'X-AAPrincipal'. The value of the header will consist of a cryptographic hash, a single space, and the value of the corresponding item. The hash will be a BASE64 SHA-1 based RFC2104 HMAC of the concatenation of the value and the secret set by AAHeaderKey, in that order. The addition of the hash and the separating space can be suppressed by setting AAHeaderKey to 'none'. The addition of the cryptographic hash makes it possible for a system receiving such a header to know with some confidence that the header came from a particular mod_ucam_webauth module and not, as a result of exploitation of one of a number of possible misconfigurations, direct from an attacker. Similar functionality, without the cryptographic protection, is available from the standard mod_headers module. AAHeaderKey Syntax: AAHeaderKey "text" | none Context: all Override: AuthConfig Module: mod_ucam_webauth A random key used to generate the cryptographic hash used to protect the values of headers added by AAHeaders from tampering and forgery. Any reasonably unpredictable string (for example an md5sum taken from a rapidly changing logfile) will be satisfactory. This parameter has no default and must be set anytime AAHeaders has a value other than none. It can be set to the (case-insensitive) string 'none' in which case no hash generation will take place. Knowledge of this key could allow an attacker to forge a request containing what appear to be header values set by this module. As with AACookieKey, for preference this directive should be placed in a file that is only readable by the user used to start Apache, commonly root. One way to achieve this, while leaving the main configuration file mainly readable, would be to put the AACookieKey directive in a file only readable by root (or whoever) that is incorporated into the main configuration using the 'Include' directive. It may also be necessary to disable the standard mod_info module since this can be use to display the Apache configuration and this will include the value assigned to AAHeaderKey. AAIgnoreResponseLife Syntax: AAIgnoreResponseLife Off|On Default: Off Context: all Override: AuthConfig Module: mod_ucam_webauth If set to 'On' the module ignores any 'life' parameter from authentication response message. Agents such as mod_ucam_webauth are expected to use this parameter to set an upper limit to the lifetime of any session that they establish so that that sessions on individual web servers do not last longer than an SSO session established on the authentication server. On rare occasions this is not appropriate so this directive is provided to override this behaviour. AAForceAuthType Syntax: AAForceAuthType Default: Ucam-WebAuth Context: all Override: AuthConfig Module: mod_ucam_webauth This directice sets the string that the module sets as Apache's internal auth_type value if it has performed authentication (c.f. mod_auth setting this to 'Basic'). This in turn is the value made available in the CGI environment. Something like 'AAForceAuthType Basic' could allow authentication systems intended for use with HTTP Basic Auth to work under Ucam-WebAuth. Versions of the module prior to 1.0.0 supported the AALogLevel directive. Support for this has been withdrawn - at present any use of this directive causes a warning to be logged; in due course use of this directive will be treated as an error. 2.3. Logout page ---------------- The recommended way to logout from resources protected by Ucam-WebAuth is to completely quit the browser. However it is possible for the module to provide a 'virtual' logout page by associating a URL with the special handler 'AALogout'. This URL need not relate to anything that exists in the file system. For example: SetHandler AALogout will cause logout.html to act as a logout page. Default page content is provided - this can be overridden using the AALogoutMsg directive: as for custom error pages, the AALogoutMsg directive can be followed by either a simple text string, a partial URL starting '/' (in which case it will be assumed to be on the current server), or a full URL in which case the user will be redirected there. The value must be quoted if it contains spaces. It's a god idea to ensure that access to the logout URL is not itself protected by Ucam-Webauth. If it is and it is visited by someone who is not yet authenticated then they will first be prompted to authenticate themselves, only then to be told that they are logged out! 2.4. Custom Error Pages ----------------------- A number of error conditions will be reported by returning an error page to the user's browser. The module may need to report 'User declined to authenticate', 'Browser not accepting session cookie', 'Bad Request', and 'General server error'. In addition, the standard authorisation modules used along with this module may raise 'Authorization Required' if the authenticated user is not actually allowed access. In all cases, how these errors are reported can be controlled by using Apache's 'Custom Error Pages' system. This allows a web designer to replace the default pages with versions that, for example, more closely match the look and feel of the site. Error pages for 'Bad Request', 'General server error' and 'Authorization Required' can be established using the standard ErrorDocument directive for status codes 400, 500 and 401. A modified 401 page will be provided if a custom one is not defined since the Apache default is misleading. The default Apache 400 and 500 pages will be used (and may well be satisfactory) if a custom page is not defined for these codes. Note that under Apache version 1 (though not version 2), the default 400 page includes the text of messages recently sent to the error log. While this does not revel any sensitive information in the case of mod_ucam_webauth, it does make the pages look somewhat 'messy'. Custom error pages for 'User declined to authenticate' and 'Browser not accepting session cookie' can be established using the AACancelMsg and AANoCookieMsg configuration parameters (see above). Default pages will be used if custom ones are not defined. Custom messages can be either a simple text string, a partial URL starting '/' (in which case it will be assumed to be on the current server), or a full URL in which case the user will be redirected there (except for 401 Authorization Required where a full URL will be ignored if provided). Values for the various '...Msg' directives must be quoted if they contain spaces. If using URLs referring to error pages on the current server, be sure that they themselves are not protected by mod_ucam_webauth. If the error document is a local one then a number of environment variables with names starting 'REDIRECT_' will contain additional information about what went wrong that could be displayed if the document is something like an SSI page or a CGI script. In particular, REDIRECT_ERROR_NOTES may contain an error message - however there may be other causes of server errors that will also set REDIRECT_ERROR_NOTES and displaying these could give away information useful to an attacker (error messages are in any case logged to the server error log). Other variables that may be available prefixed by 'REDIRECT_' include those described below under Authentication Information. 3. Authentication Information ============================= Following a successful authentication, Apache's internal view of current user is set to that provided by the authentication service. As a result this value can be logged using the '%u' log format token (which is the third entry in 'Common Log Format'), and will appear as the value of the environment variable REMOTE_USER in the environment of CGI programs, SSI pages, etc. Other items of authentication information are made available as environment variables, and optionally as HTTP headers (see the AAHeaders directive). If required, these items can be logged using the log format tokens '%{...}e' (for environment variables) or %{...}i' (for header values). Environment variable names are formed by prepending 'AA' to an upper-case version of the item name; header names are formed from the item name by appending 'X-AA'. For example, the ID of the current user will be available in the environment variable 'AAPRINCIPAL' and optionally in the header 'X-AAPrincipal'. Available authentication information: issue The time/date at which the current authentication session started. This date/time is in the format similar to that specified by RFC 3339 except that time-offset is always 'Z' and punctuation is omitted e.g. "19850412T232050Z" would be 23:20:50 on 12th April 1985. last The time/date of the last recorded activity by the user. Note that his will be the same as AAISSUE unless inactivity timeouts are in use. This date/time is in the same format as AAISSUE. life The maximum lifetime of the current authentication, in seconds. timeout The inactivity timeout currently in force, in seconds. 0 implies that inactivity timeouts are not in use. id The identifier (serial number) of the authentication service response on which the users authentication is based. principal Same as REMOTE_USER auth This indicates which authentication type was used if authentication was established by interaction with the user. This value consists of a single text token. The only value currently in use is 'pwd'. sso This indicates which authentication types were previously used if authentication was established based on previous successful authentication interactions with the user. This value consists of a a sequence of text tokens separated by ','. The only value currently in use is 'pwd'. 4. Error Messages ================= mod_ucam_webauth optionally writes errors, warnings, information messages and debugging information to the server error log. Exactly what is logged is controlled by Apache's LogLevel directive. With LogLevel set to 'Notice' (the default) or higher, only messages about unexpected events will be logged. The messages that may be produced at 'Notice' or higher are listed below with extended explanations. The letter in brackets indicates the severity at which the messages are logged: C - Critical, E - Error, W - Warning. '%s' in a message indicates that additional information will be included at that position: AACookiePath %s is not a prefix of %s (C) The value of the AACookiePath directive for the current request, and therefore the path component that will be used when setting a session cookie, isn't a prefix of the current URI. This can't work, because any cookie that is set to carry authentication information about the current URL won't be returned when that URL is requested in the future. This is probably the result of a configuration error involving the scope of a or block, or .htaccess file, and an AACookiePath directive. The user will have received a '500 Server error' message AAHeaders used but AAHeaderKey not set (E) The AAHeaderKey directive must be used to set a key if the AAHeaders directive has a value other than 'none': there is no default and any requests for which AAHeaderKey us unset will fail. The user will have received a '500 Server error' message. Access to %s failed: AACookieKey not defined (C) The AACookieKey directive must be used to set a key: there is no default and the module won't work otherwise. The user will have received a '500 Server error' message Authentication error, status = %s, %s (E) Either a authentication service response itself contained an error indication (if status < 600), or mod_ucam_webauth could not validate the response. Possible codes and messages include the following. The user will have received a '400 Bad request' message. 510: No mutually acceptable types of authentication available The request to the authentication service asked for authentication types that the authentication service does not support. This should not be able to happen with mod_ucam_webauth. 520: Unsupported authentication protocol version The request to the authentication service used a version of the request protocol that the authentication service does not support. This should not be able to happen with mod_ucam_webauth. 530: Parameter error in authentication request The request to the authentication service contained parameters that the authentication service could not parse or did not understand. This should not be able to happen with mod_ucam_webauth. 540: Interaction with the user would be required The request to the authentication service required that authentication should take place with no interaction with the user, but this was not possible. This should not be able to happen with mod_ucam_webauth. 560: Web server not authorised to use the authentication service The web server running mod_ucam_webauth (not: not the user's web browser) is not authorised to use the authentication service. Contact the authentication service administrators for more information. 570: Operation declined by the authentication service The authentication service declined to do what it was asked - further information may be included. One possible reason is that the user is using a browser that the authentication service knows doesn't correctly support the Ucam-Webauth system. 600: Wrong protocol version (%s) in authentication service response The response from the authentication service used a version of the request protocol that mod_ucam_webauth does not support. 600: Can't to parse issue time (%s) in authentication service response mod_ucam_webauth is unable to read the issue time contained in the authentication service response 600: WLS response issued in the future (local clock incorrect?); issue time %s The issue time of the authentication service (WLS) response appears to be in the future. This suggests that the clock on the web server running mod_ucam_webauth may be wrong (see 'Timekeeping' above) 600: WLS response issued too long ago (local clock incorrect?); issue time %s The issue time of the authentication service (WLS) response appears to be too long ago. This could be because the clock on the web server running mod_ucam_webauth is wrong (see 'Timekeeping' above); it could also mean that someone is (intensionally or otherwise) trying to replay an old response in an attempt to authenticate. 600: Non first-hand authentication under ForceInteract A authentication service response was received that indicates that the user authenticated using the authentication service's 'single sign on' feature but this isn't allowed by the setting of AAForceInteact. Baring a bug, this suggests that someone is trying to circumvent AAForceInteact. 600: Missing or invalid signature in authentication service reply The signature on the authentication service response failed to validate. Baring a bug, this should mean that the response has been corrupted, tampered with, or is forged. 600: Web server configuration error Some web server configuration problem (probably lack of the necessary public key) prevented verification of the response. Other messages will have already been logged pinpointing the problem. 600: Requested session expiry time less that one second Somehow the requested lifetime of a session appears to be zero or negative. This is probably a bug. Browser not accepting session cookie (W) The module checks that the user's browser is accepting the session cookie, since otherwise the user will be repeatedly redirected to the login server. This appears not to be the case (though the check can be fooled in some circumstances). The user will have received a message explaining what happened (see AANoCookieMsg). Session cookie invalid or key has changed (E) The signature used to protect the session cookie for tampering and forgery failed to validate. Baring a bug, this suggests that the offered cookie has been corrupted or tampered with, or is forged. However it can also appear if AACookieKey is changed or if the same cookie (same name, domain, path) ends up being used in conjunction with two different cookie keys, for example from two different blocks each containing a different AACookieKey setting. The module will behave as if the cookie hadn't been there and redirect the user to the login service. Error opening public key file %s: %s (C) While attempting to open a file (probably a public key file) something went wrong. The system's description of the error is included. The user will (indirectly) receive a '400 Bad request' message. Error reading public key from %s (additional information may follow) (C) When validating the signature on a response, the corresponding public key could not be parsed. The OpenSSL error message (which may not be very helpful) will follow. The key file is probably corrupt, or not what you are expecting, or something. The user will (indirectly) receive a '400 Bad request' message. Error validating WLS response signature (additional information may follow) (C) The signature on a response from the WLS (authentication service) failed to validate. Baring a bug, this should mean that the response has been corrupted, tampered with, or is forged. The OpenSSL error message (which may not be very helpful) will follow. The user will (indirectly) receive a '400 Bad request' message. Failed to parse own URL (C) Something went horribly wrong while trying to generate the canonical URL for the current request. This might be the result of an unusual web server configuration, but is probably a bug. The module will plough-on regardless but other problems will probably arise. Failed to validate WLS response ID %s: %s: %s (E) Summary message produced whenever a response fails to validate.The user will (indirectly) received a '400 Bad request' message. Session cookie has issue date in the future Session cookie has last used date in the future (E) The issue or last used date in the session cookie appears to be in the future. Since this can't happen, it could mean that the response has been corrupted or tampered with, or that the clock on the web server has been reset. The user will have received a '400 Bad request' message. Session cookie issue date incorrect length Session cookie last use date incorrect length Session cookie lifetime unreadable (E) The issue or last used date, or the lifetime field, in the session cookie is the wrong length. This shouldn't be possible without the signature also not validating so it is probably a bug. URL in WLS response doesn't match this URL - %s != %s (E) The URL embedded in a authentication service (WLS) response doesn't match the URL it was submitted to. This could be the result of an obscure configuration, but will also happen if a response intended for one web server is replayed to another in the hope of forging authentication. Redirect required on a POST request - POSTed data will be lost (W) A redirect to the authentication service was required (either for initial authentication or because authentication had expired) when servicing a POST request. Because of the way that mod_ucam_webauth is implemented any parameters submitted along with the POST request will be lost. -- $Id: README.Config,v 1.5 2007-04-13 16:51:31 jw35 Exp $