more whitespace tweaks
[raven/abandoned/asp.git] /
1University of Cambridge Classic ASP/VBScript Raven Authentication Module - v.1.0 (29/04/2014)
6This software comprises a VBScript class 'Ucam_Webauth' and sample
7files that provide a Classic ASP/VBScript implementation of a 'Raven'
8authentication module; Raven is the web authentication protocol used
9by the University of Cambridge, UK. The logic and code of the
10'Ucam_Webauth' class are loosely based on the PHP Raven authentication
11class provided at
12- For a full description of the latest Raven specification and an explanation
13of how Raven works, go to
14- This software was originally created for the Careers Service,
15University of Cambridge by For support, please
18Files and folders
20- [certificates]: Temporary location for Raven public key certificates.
21- [js]: Folder containing Javascript cryptography libraries.
22- [docs]: Supporting documentation.
23- [logs]: Possible location for log files created by the module.
24- Default.asp: A sample file showing how the 'Ucam_Webauth' class is used
25to provide Raven authentication.
26- Test.asp: A test file for unit testing the 'Ucam_Webauth' module using the
27'Ucam_RavenWLS' dummy Raven server (separate project, not included).
28- Ucam_Webauth.vbs: The main 'Ucam_Webauth' VBScript class.
30Platform requirements
32This module has been tested on IIS7 with .NET Framework set to
33'No managed code', ie. classic ASP.
37### Cryptographic functions
38Cryptographic functions are provided by the Javascript libraries within the
39'js' folder. These libraries are versions of the client-side Javascript
40libraries provided at
41but modified to run server-side. There is no need to install any
42additional cryptography libraries.
44### Install Raven certificates
45The authentication module uses the Raven public key certificate at
46 to verify authentication responses.
47Download the certificate from and copy
48to the 'certificates' folder provided with this authentication module
49download - the 'certificates' folder is a temporary location for the
50certificate while you get the module up and running. You will need to supply
51the full path to the 'certificates' folder as either a 'key_dir' argument
52to the 'Ucam_Webauth' constructor or by modifying the 'Ucam_Webauth'
53variable 'DEFAULT_KEY_DIR' directly.
55Once you have everything working, move the 'certificates' folder
56to a new location on your webserver that is not web- or publicly-accessible
57and modify the 'key_dir' string accordingly.
59- NOTE: you may have to change the name of the key file from 'pubkey2.crt'
60to '2.crt'.
62If you're using the Raven test server
63( for testing purposes, make sure
64you install the test server keys instead, but ensure you remove these keys
65before using the authentication module in a production environment, as
66recommended by the demo Raven server:
68> It is vital to keep these demo keys seperate from keys
69> used with a production service - failure to do so could
70> allow an attacker to successfully replay a response
71> from the demonstration server, which anyone can easily
72> obtain, against a production service.
74Getting started
77The 'Ucam_Webauth' VBScript class must be used within an ASP server-side page
78as it interacts directly with a user's browser session. To use the
79'Ucam_Webauth' VBScript class:
087f7f48 811. Ensure the 'Ucam_Webauth.vbs' class file and the folder 'js' are in the
82same directory as your ASP script. The folders 'certificates' and 'logs' may
83also be located here temporarily.
087f7f48 842. Include the 'Ucam_Webauth.vbs' class file in the 'head' of your ASP file:
87 <head>
88 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
89 <!--#include file="Ucam_Webauth.vbs"-->
90 </head>
2ffb56d1 91
087f7f48 923. Set up the initial arguments for the 'Ucam_Webauth' class:
d3465de2 93
94 Set args = CreateObject("Scripting.Dictionary")
95 args.Add "hostname", "localhost"
96 args.Add "auth_service", ""
97 args.Add "key_dir", "C:/Ucam_Webauth/certificates"
2ffb56d1 98
0ec3b31c 99 'args' is an associative array of *text* strings so parameter values must
100be converted into strings, ie. numbers and booleans must be supplied within
101quotes as in "23", "TRUE", "FALSE".
102A full list of allowed parameters is provided at the end of this README.
087f7f48 1044. Create an instance of the 'Ucam_Webauth' class from within your ASP
105server page and initialize with setup variables:
107 Set oUcam_Webauth = New Ucam_Webauth
108 Call oUcam_Webauth(args)
2ffb56d1 109
087f7f48 1105. Call 'Authenticate()' on the Ucam_Webauth object and act according to
111the value returned:
17d19429 113 Select Case oUcam_Webauth.Authenticate()
2ffb56d1 114
17d19429 115 Case oUcam_Webauth.AUTHENTICATE_INCOMPLETE
2ffb56d1 116
117 ...
118 Exit Sub
2ffb56d1 119
2ffb56d1 121
17d19429 122 ...
2ffb56d1 123
2ffb56d1 125
17d19429 126 ...
2ffb56d1 127
17d19429 128 Case oUcam_Webauth.AUTHENTICATE_COMPLETE_ERROR
2ffb56d1 129
17d19429 130 ...
2ffb56d1 131
17d19429 132 End Select
2ffb56d1 133
17d19429 134 The four possible return values of 'Authenticate()' are:
136- AUTHENTICATE_INCOMPLETE : The authentication process has yet to complete.
137The user may have been redirected to the Raven server and has yet to enter
138their login details.
139- AUTHENTICATE_COMPLETE_AUTHENTICATED : The authentication process completed
140and the user has been successfully authenticated.
142completed and the user was not successfully authenticated.
143The user may have clicked 'Cancel' at the Raven server.
144- AUTHENTICATE_COMPLETE_ERROR : There was an error during the authentication
145process forcing the authentication cycle to terminate early.
147As the 'Authenticate()' function may need to send HTTP headers, it must be
148called before any output (e.g. HTML, HTTP headers) is sent to the browser.
150The 'Default.asp' file provided is a sample of a simple server page using
151the 'Ucam_Webauth' VBScript class.
153Overview of Raven process
155A diagram of the Raven authentication process is located within the 'docs'
156folder as [I - Overview of Raven Authentication Process.pdf].
158The authentication cycle consists of the following key stages:
160#### User first tries to access authenticated page
161User tries to load an authenticated page on a particular website.
162The 'Ucam_Webauth' class is loaded and the 'Authenticate()' function is called.
163If no authentication cookie is found to indicate the user is authenticated,
164the user's browser is redirected to a separate Raven server using a special
165'Authentication Request'. The authentication request consists of a series of
166authentication parameters encoded into the URL redirect as name/value pairs.
168#### User is prompted for login information
169The Raven server interprets the authentication request sent by the main
170website and prompts the user for their username and password. The user may
171then be successfully authenticated or may decide to click 'Cancel'. They are
172redirected back to the main website with a series of 'Authentication Response'
173parameters encoded into a 'WLS-Response' GET variable.
175#### User redirected back to main webserver
176The user's original page is loaded again and 'Authenticate()' is called a
177second time. 'Ucam_Webauth' processes the new 'WLS-Response' GET value and,
178if it's valid, sets an authentication cookie on the user's browser. The
179user's original page is then loaded again.
181#### User redirected back to main webserver again
182With an authentication cookie now set, 'Authenticate()' checks the status
183code contained in the value of the authentication cookie and returns either
186'AUTHENTICATE_COMPLETE_AUTHENTICATED' is returned , the original page can
187go on to display authenticated content to the user.
189Specifics of module
191The 'Authenticate()' function is the overarching authentication function of
192'Ucam_Webauth'. It performs some basic sanity checks using 'CheckSetup()'
193then uses 'GetCurrentState()' to establish the current state of the
194authentication process before branching accordingly. The possible return
195values of 'GetCurrentState()' are:
198A completely fresh authentication. 'SendAuthenticationRequest()' [*1*] is
199then triggered which performs some basic data checks, sets the authentication
200cookie to 'AUTHENTICATIONCOOKIE_REDIRECT_WLS' (to record where we are in the
201authentication process) and redirects the user's browser to the Raven
202authentication server with a series of authentication parameters
203encoded as name/value pairs.
206The Raven authentication server has processed the user and has returned the
207user's browser back to the original website with a series of authentication
208response parameters encoded into the 'WLS-Response' GET variable.
209'ProcessAuthenticationResponse()' [*2*] is then called which checks the
210validity of the 'WLS-Response' value, sets an authentication cookie and
211redirects the user back to the original page.
214A valid authentication cookie has been set
216'ProcessAuthenticationCookie()' [*3*] is then called which checks the
217validity of the cookie. If the cookie has expired,
218'SendAuthenticationRequest()' is called again in case the user needs to
219reauthenticate themselves. If the cookie is still valid, an
220'AUTHENTICATE_COMPLETE_XXX' value is returned, indicating that the
221authentication cycle has completed successfully.
222NOTE: this may be true if the user has cancelled the authentication process,
223in which case 'AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED' will be returned.
226An error occurred, breaking the authentication cycle and returning
227AUTHENTICATE_COMPLETE_ERROR to 'Authenticate()'. This return value will
228also be generated by the other functions above if they generate an error.
230## Accompanying diagrams
231Detailed diagrams of the Raven process flow for (i) a successful
232authentication (ii) a cancelled authentication, are located in the 'docs'
233folder as [II - Ucam_Webauth - Flowchart for Valid Authentication.pdf] and
234[III - Ucam_Webauth - Flowchart for Cancelled Authentication.pdf], respectively.
236The numbers on these diagrams correspond to the three key secondary functions
237described above:
238- *1*. SendAuthenticationRequest()
239- *2*. ProcessAuthenticationResponse()
240- *3*. ProcessAuthenticationCookie()
242Other important functions include:
244### ResetState()
245Attempts to reset state as if a new user has just loaded a fresh browser
246window. This is typically used when a user has experienced an error and we
247want to give them a fresh opportunity to try again.
249### check_signature(...)
250Checks the signature provided by the Raven server, when it signed the
251'WLS-Response' variable, is a valid signature for the data. This ensures the
252data has not been tampered with.
254### hmac_sha1(...)
255Creates a hash value for signing the local authentication cookie.
257### wls_encode/decode(...)
258Encoding/decoding functions to allow base64 signatures to be sent within URLs.
260Possible arguments to 'Ucam_Webauth'
262(Based on documentation for PHP Raven authentication module)
264- log_file :
265The location for a log file that will record progress and track possible
266errors. The folder containing the file must be read/writable by the webserver.
267Default: log.txt
269- response_timeout :
270Responses from the central authentication server are time-stamped.
271This parameter sets the period of time in seconds during which these
272responses are considered valid.
273Default: 30 seconds.
275- key_dir :
276The name of the directory containing the public key certificate(s) required
277to validate the authentication responses sent by the server.
278Default: '/etc/httpd/conf/webauth_keys'.
280- max_session_life :
281The maximum period of time in seconds for which an established session will
282be valid. This may be overriden if the authentication reply contains a
283shorter 'life' parameter. Note that this does NOT define an expiry time for
284the session cookie. Session cookies are always set without an expiry time,
285causing them to expire when the browser session finishes.
286Default: 7200 (2 hours).
288- timeout_message :
289A re-authentication by the authentication service will be triggered when an
290established session expires. This option sets a text string which is sent to
291the authentication server to explain to the user why they are being asked to
292authenticate again. HTML markup is suppressed as for the description
293parameter described below.
294Default: 'your login to the site has expired'.
296- hostname (required) :
297The fully-qualified TCP/IP hostname that should be used in request URLs
298referencing the Ucam_Webauth-enabled application. This *must* be set, as it
299is needed for multiple reasons - primarily security but also to avoid varying
300hostnames in URLs leading to failed or inconsistent authentication.
301No default.
303- cookie_key (required):
304A random key used to protect session cookies from tampering. Any reasonably
305unpredictable string (for example the MD5 checksum of a rapidly changing
306logfile) will be satisfactory. This key must be the same for all uses of the
307web authentication system that will receive the same session cookies (see the
308cookie_name, cookie_path and cookie_domain parameters below).
309No default.
311- cookie_name :
312The name used for the session cookie.
313When used for access to resources over HTTPS the string '-S' is appended to
314this name.
315Default: 'Ucam-Webauth-Session'.
317- cookie_path :
318The 'Path' attribute for the session cookie. The default is the directory
319component of the path to the script currently being executed. This should
320result in the cookie being returned for future requests for this script and
321for the other resources in the same 'directory'; see the important
322information about the cookie_key parameter above.
323Default: '/'.
325- cookie_domain :
326The 'Domain' attribute for the session cookie. By default the 'Domain'
327attribute is omitted when setting the cookie. This should result in the
328cookie being returned only to the server running the script. Be aware that
329some people may treat with suspicion cookies with domain attributes that are
330wider than the host setting the cookie.
331No default.
333- auth_service : The full URL for the web login service to be used.
334Default: ''
336#### Authentication request properties
337The following setup parameters prefixed with 'authrequest_' relate to
338properties that will be sent to the authentication server as part of an
339authentication request:
341- authrequest_desc : A text description of the resource that is requesting
342authentication. This may be displayed to the user by the authentication
343service. It is restricted to printable ASCII characters (0x20 - 0x7e) though
344it may contain HTML entities representing other characters. The characters
345'<' and '>' will be converted into HTML entities before being sent to the
346browser and so this text cannot usefully contain HTML markup.
347No default.
349- authrequest_params : Data that will be returned unaltered to the WAA in
350any 'authentication response message' issued as a result of this request.
351This could be used to carry the identity of the resource originally requested
352or other WAA state, or to associate authentication requests with their
353eventual replies. When returned, this data will be protected by the digital
354signature applied to the authentication response message but nothing else is
355done to ensure the integrity or confidentiality of this data - the WAA MUST
356take responsibility for this if necessary.
357No default.
359- authrequest_skew : Interpretation of response_timeout is difficult if the
360clocks on the server running the PHP agent and on the authentication server
361are out of step. Both servers should use NTP to synchronize their clocks,
362but if they don't then this parameter should be set to an estimate of the
363maximum expected difference between them (in seconds).
364Default: 0.
366- authrequest_fail :
367If TRUE, sets the fail parameter in any authentication request sent to the
368authentication server to 'yes'. This has the effect of requiring the
369authentication server itself to report any errors that it encounters, rather
370than returning an error indication. Note however that even with this parameter
371set errors may be detected by this module that will result in authentication
372failing here.
373Default: FALSE.
375- authrequest_iact :
376If TRUE, then the 'iact' parameter provided to the authentication server is
377set to 'yes'. If FALSE, then the 'iact' parameter is set to 'no'. If no value
378is provided for 'authrequest_iact', the 'iact' parameter is left blank.
379The value 'yes' for 'iact' requires that a re-authentication exchange takes
380place with the user. This could be used prior to a sensitive transaction in
381an attempt to ensure that a previously authenticated user is still present
382at the browser. The value 'no' requires that the authentication request will
383only succeed if the user's identity can be returned without interacting with
384the user. This could be used as an optimisation to take advantage of any
385existing authentication but without actively soliciting one. If omitted or
386empty, then a previously established identity may be returned if the WLS
387supports doing so, and if not then the user will be prompted as necessary.
f560b040 388Default: omitted.