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