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