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