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