README.Config

     ===============================================================
     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 information about configuring the 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 2.0, this functionality is provided by the mod_auth
module. In Apache 2.2 and 2.4, 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.

The one exception to this relates to "ptags". These are new to version
3 of the UcamWebAuth protocol; they are a set of tags that may apply
to a user. Site administrators may configure mod_ucam_webauth to
require that particular ptags be set (see AARequiredPtags below) in
order for authentication to succeed. Currently, the only ptag set by
the University's Raven server is "Current", meaning that the
authenticated user is a current student or member of
staff. mod_ucam_webauth's default behaviour is to require this tag to
be set i.e. to only authenticate current staff and students. This is
the same behaviour as was found in version 2 of the UcamWebAuth
protocol.

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
because they work by combining their 'authentication' and
'authorisation' phases in such a way that one can't be used without
the other. It is possible to use mod_authnz_ldap to perform
'authorisation' decisions in conjunction with 'authentication'
provided by mod_ucam_webauth.


2. Configuration
================

If the module has been built as a dynamic shared object 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.

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"
  <Directory "path to protected directory">
    AuthType Ucam-WebAuth
    Require valid-user
  </Directory>

An alternative simple configuration will allow access to the resources
to users with a Ucam-WebAuth login, to client computers with hostnames
ending .cam.ac.uk, or to those using a CUDN IPv6 address, but not
otherwise:

  AACookieKey "some random string"
  <Directory "path to protected directory">
    Require host .cam.ac.uk
    Require ip 2001:630:210::/44
    AuthType Ucam-WebAuth
    Require valid-user
  </Directory>

In these examples the resources to be protected are selected by a
<Directory> directive; resources specified by <Location> or <Files>
directives can also be protected in the same way. 'AuthType' must be
set to 'Ucam-WebAuth'. A directive 'Require user', 'Require group' or
'Require valid-user' must appear before authentication will take
place.

See standard Apache 2.4 documentation for more details of the
'Require' directive. (Apache 2.2 and earlier use a more complictated
authorization language involving 'Order', 'Allow', 'Require', and
'Satisfy' directives.)

The AACookieKey directive is required, though it can appear either
outside the <Directory> 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 into 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
ucam_webauth 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
<VirtualHost>, <Directory>, <Location>, or <File> blocks, and in
.htaccess files if 'AllowOverride AuthConfig' is in effect.

AAAuthService

  Syntax:   AAAuthService <URL>
  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 <URL>
  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 <text>
  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 cannot contain HTML markup.

AAResponseTimeout

  Syntax:   AAResponseTimeout <seconds>
  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 <seconds>
  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 doesn'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 <file-path>
  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 <seconds>
  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 <seconds>
  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 <text|'none'>
  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 good 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" | "file:filename"
  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.

  If the parameter starts with "file:", the key will instead be read
  from the file named in the rest of the string. Relative paths will
  be interpreted from the server root. The key will be formed from the
  first 64 bytes of the named file, or the entire file, whichever is
  shorter. If the file does not provide at least 16 bytes, the server
  will abort with an error. Using the "file:" prefix is not permitted
  in .htaccess files.

  On Linux, create a separate cookie.key file with e.g.

    $ sudo bash
    # ( umask 0077 ; head -c 64 /dev/random >/etc/apache2/cookie.key )

  and then use that with

    AACookieKey file:cookie.key

  Alternatively,

    AACookieKey file:/dev/urandom

  will request from the kernel's random-byte generator a new cookie
  key each time the server rereads its configuration, and avoids a
  secret on the file system. However, this will trigger a round trip
  to Raven for all currently-authenticated users every time Apache is
  restarted/reloaded. While not a major issue, this will, for example,
  result in the loss of POST data. (On the other hand, using
  "AAHeaderKey file:/dev/urandom" would be pointless: the whole point
  of AAHeaderKey is to establish a shared secret with other systems.)

  The key must not disclosed, since with knowledge of the key an
  attacker can forge authentication. Putting the key directly into
  a main configuration file can cause two problems:

    - Read access to this Apache configuration file must be
      restricted.

    - Access to the server information page generated by the standard
      mod_info module must also be restricted, since that will also
      reveal the parameter of the AACookieKey directive.

  Storing the key in a separate cookie.key file, only readable to
  root, avoids both these risks.

AACookieName

  Syntax:   AACookieName <name>
  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 '-<port>' is appended to this name, and
  when used for access to resources over https the string '-S' is also
  appended..

AACookiePath

  Syntax:   AACookiePath <URL-path>
  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

    <Location /protected>
      AACookieKey foobar
      AACookiePath /protected/
    </location>

  will cause problems when a browser tries to access
  http://<whatever>/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 <hostname>
  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.

AACookieForceSecure

  Syntax:   AACookieForceSecure Off|On
  Default:  AACookieForceSecure Off
  Context:  all
  Override: AuthConfig
  Module:   mod_ucam_webauth

  By default, mod_ucam_webauth sets the "secure" attribute on its
  session cookie when it is invoked over https. The "secure" attribute
  instructs the browser to only return the cooker over https. There
  are a few circumstances (e.g. running on a server which talks http
  to a proxy that talks https to the user) where you may wish to set
  the "secure" attribute even when mod_ucam_webauth is not being
  invoked over http. In that case, set AACookieForceSecure to
  On. Note, though, that if the browser is using http, then it will
  not return session cookies with the "secure" attribute set. Unless
  you are sure you know what you are doing, do not change this flag.

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.

AARefuseInteract

  Syntax:   AARefuseInteract Off|On
  Default:  AARefuseInteract Off
  Context:  all
  Override: AuthConfig
  Module:   mod_ucam_webauth

  If set, the authentication service will not attempt to interact with
  the user.  If the authentication service cannot report the user's
  identity without interacting with them, it will report an error.  It
  does not make sense to set this option and AAForceInteract at the same
  time.

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.

AARequiredPtags

  Syntax:   AARequiredPtags none | item[ item...]
  Default:  AARequiredPtags Current
  Context:  all
  Override: AuthConfig
  Module:   mod_ucam_webauth

  If set, this specifies which ptags the user must have for
  authentication to succeed. The only currently-specified ptag is
  "Current", which is attached to all current students and members of
  staff. The default behaviour is to require this tag. Setting
  AARequiredPtags to none would allow users without the "Current" ptag
  to be authenticated.

AAPtagsIncorrectMsg
  Syntax:   AAPtagsIncorrectMsg <document|'none'>
  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 lacks a required ptag. If unset or 'none'
  (case insensitive), a standard message will be displayed. <document>
  can be a text message (enclosed in quotes), or a partial or full
  URL. See the Custom Error Pages section below.

AACancelMsg

  Syntax:   AACancelMsg <document|'none'>
  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 AAFail is not set). If unset or 'none' (case insensitive), a
  standard message will be displayed. <document> can be a text message
  (enclosed in quotes), or a partial or full URL. See the Custom Error
  Pages section below.

AANeedInteractMsg

  Syntax:   AANeedInteractMsg <document|'none'>
  Context:  all
  Override: AuthConfig
  Module:   mod_ucam_webauth

  If set, this identifies the message that will be displayed on the
  user's browser if AARefuseInteract is enabled and the authentication
  service would have to interact with the user in order to report
  their identity (assuming that AAFail is not set). If unset or
  'none' (case insensitive), a standard message will be
  displayed. <document> can be a text message (enclosed in quotes), or
  a partial or full URL. See the Custom Error Pages section below.

AANoCookieMsg

  Syntax:   AANoCookieMsg <document|'none'>
  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. <document> can be a text message (enclosed in quotes), or
  a partial or full URL. See the Custom Error Pages section below.

AALogoutMsg

  Syntax:   AALogoutMsg <document|'none'>
  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. <document>
  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 <whatever>
    AAAlwaysDecode On
    <Location /login.html>
      AuthType WebAuth
      Require valid-user
    </Location>

  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" | "file:filename" | 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 any time 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. See
  the description of AACookieKey for more information on how to read
  the key from a file only readable by the user used to start Apache,
  commonly root.

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 the
  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 <type>
  Default:  Ucam-WebAuth
  Context:  all
  Override: AuthConfig
  Module:   mod_ucam_webauth

  This directive 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 UcamWebAuth
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:

  <Location "/logout.html">
    SetHandler AALogout
  </Location>

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 good 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', 'Forbidden',
and 'Authorization Required' can be established using the standard
ErrorDocument directive for status codes 400, 500, 403, 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', 'Interaction
with user would be required', 'User lacking a required ptag', and
'Browser not accepting session cookie' can be established using the
AACancelMsg, AANeedInteractMsg, AAPtagsIncorrectMsg, 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

ptags

  Which ptags, if any, were set by the authentication service. The
  only currently-defined ptag is "current", indicating a current
  student or member of staff.

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 <Location ...> or <Directory ...> 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 is 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 (NB 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 parse issue time (%s) in WLS 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 (intentionally 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. Barring 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. Barring 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. Barring 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 <Directory ...> 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) Something went wrong while attempting to open a file (probably a
  public key file). 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. Barring 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 shouldn't be possible, 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.

AARequiredPtags: unrecognised ptag - expecting 'Current' or 'None'

  A ptags value in AARequiredPtags was not understood. This means you
  specified something other than "Current" or "none" (both case
  insensitive) or the empty string (equivalent to the default setting
  i.e. "Current"). The module will decline to proceed at this point,
  so the user will get a "500 Internal Server Error" page.

cookie status 601 => ptags mismatch => forbidden
Ptags mismatch, set=%s, required=%s

  (E) The user lacks some of the required ptags, so access has been
  denied them.