1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 4 <html xmlns="http://www.w3.org/1999/xhtml"> 5 <head> 6 <title>LoginRedirect and Login Modules</title> 7 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 8 <link href="styles.css" rel="stylesheet" type="text/css" /> 9 </head> 10 11 <body> 12 <h1>LoginRedirect and Login Modules</h1> 13 14 <p>The <code>LoginRedirect</code> and <code>Login</code> modules provide a 15 "single sign-on" environment for WebStack applications. Unlike the 16 authenticator-only approach, each application or part of an application 17 utilising this mechanism must be wrapped inside a 18 <code>LoginRedirectResource</code> object which determines whether a given 19 transaction contains information identifying the application's user.</p> 20 21 <h2>How the Modules Work</h2> 22 23 <p>When a request arrives in the application, the following things happen:</p> 24 <ol> 25 <li>The <code>LoginRedirectResource</code> examines the transaction and 26 attempts to find out whether it identifies a user.</li> 27 <li>Should sufficient information be present in the transaction, the user 28 is allowed to access the application and is identified in the normal way 29 (ie. the <code>get_user</code> method on the transaction object).</li> 30 <li>Otherwise, a redirect occurs to a login screen provided by a 31 <code>LoginResource</code> object which then presents a login form to be 32 completed by the user.</li> 33 <li>The <code>LoginResource</code> object then receives the completed form 34 information and verifies the identity of the user, testing the supplied 35 credentials against the credentials database specified in the deployment 36 of the resource.</li> 37 <li>Upon successful authentication, the user is redirected back to the 38 application, guarded by <code>LoginRedirectResource</code> which should 39 let the user gain access.</li> 40 </ol> 41 42 <h2>Introducing LoginRedirectResource</h2> 43 44 <p>The easiest way of introducing <code>LoginRedirectResource</code> objects 45 is to do so in the adapter code, as described in <a 46 href="writing-adapters.html">"Writing Adapters"</a>. The most significant 47 difference between deploying normal resources and 48 <code>LoginRedirectResource</code> objects is the special way in which such 49 objects are initialised and that they themselves contain the actual resources 50 of the application which provide the real functionality.</p> 51 52 <p>Here is what the deployment of <code>LoginRedirectResource</code> objects 53 often looks like:</p> 54 <pre>from WebStack.Resources.LoginRedirect import LoginRedirectResource, LoginRedirectAuthenticator 55 56 deploy( 57 LoginRedirectResource( 58 login_url="http://localhost:8081", 59 app_url="http://localhost:8080", 60 resource=[some resource object which provides the real application behaviour], 61 authenticator=LoginRedirectAuthenticator(secret_key="horses"), 62 anonymous_parameter_name="anonymous", 63 logout_parameter_name="logout" 64 ) 65 )</pre> 66 67 <p>Certain parts of the resource are configurable, according to which other 68 services may exist in or alongside the deployed application.</p> 69 70 <div class="WebStack"> 71 <h3>WebStack API - LoginRedirectResource Initialisation</h3> 72 73 <p>The following parameters must be provided when initialising a 74 <code>LoginRedirectResource</code> object:</p> 75 <dl> 76 <dt><code>login_url</code></dt> 77 <dd>This specifies the location of the separate login application or 78 resource which presents a login screen to unidentified users and logs 79 them in.</dd> 80 <dt><code>app_url</code></dt> 81 <dd>This specifies the location of the application itself - it must 82 therefore be updated according to where the application is eventually 83 deployed.</dd> 84 <dt><code>resource</code></dt> 85 <dd>This provides the resource object which contains the application 86 code, or at least the entry point into various parts of the application 87 code.</dd> 88 <dt><code>authenticator</code></dt> 89 <dd>This provides the authenticator object which decides whether a user 90 is recognised or not. The special 91 <code>LoginRedirectAuthenticator</code> is recommended and must itself 92 be configured using a <code>secret_key</code> parameter which is used 93 to protect user-related information exchanged over the network - the 94 value provided for <code>secret_key</code> must be unguessable and kept 95 secret from unauthorised individuals.</dd> 96 <dt><code>anonymous_parameter_name</code></dt> 97 <dd>An optional parameter providing the name of a request parameter (see 98 <a href="parameters.html">"Request Parameters and Uploads"</a>) which, 99 if specified, permits a user to access an application without being 100 formally identified. If omitted, all users will be required to identify 101 themselves explicitly.</dd> 102 <dt><code>anonymous_username</code></dt> 103 <dd>An optional parameter providing the name given to anonymous users 104 which is returned when a transaction's <code>get_user</code> method is 105 called. By default, <code>anonymous</code> is used for such users.</dd> 106 <dt><code>logout_parameter_name</code></dt> 107 <dd>An optional parameter providing the name of a request parameter 108 which, if specified, permits a user to log out of an application. If 109 omitted, no means of logging out will be available, although deleting 110 browser cookies will probably have the desired effect.</dd> 111 <dt><code>logout_url</code></dt> 112 <dd>An optional parameter which indicates the location of the resource 113 visited when a user logs out. By default, the location is a path to the 114 root resource in the server environment of the application.</dd> 115 <dt><code>use_logout_redirect</code></dt> 116 <dd>An optional parameter which determines whether users logging out of 117 an application will be redirected to the <code>logout_url</code> or 118 not. By default, users are redirected, but if a false value is given 119 for this parameter, a simple page is presented to the user informing 120 them of the situation - it is recommended that a subclass of 121 <code>LoginRedirectResource</code> be employed should more informative 122 pages be required.</dd> 123 </dl> 124 </div> 125 126 <h3>Redirection From/To the Application</h3> 127 128 <p>Some server/framework environments do not permit automatic redirection 129 back to the application, notably Apache/mod_python. In such cases, a success 130 screen is presented to the user with a link to the application they were 131 attempting to access.</p> 132 133 <h3>The Role of Authenticators</h3> 134 135 <p>In this mechanism, authenticators are employed, but only to verify the 136 credentials of users when <code>LoginResource</code> or 137 <code>LoginRedirectResource</code> objects are accessed. Although it should 138 be possible to reuse <a href="authenticators.html">application-wide 139 authenticator</a> classes in conjunction with <code>LoginResource</code>, 140 such classes will not provide the additional functionality required to 141 support the "single sign-on" aspects of this mechanism - mixing in such 142 classes with <code>LoginAuthenticator</code> may provide a solution to this 143 issue, however.</p> 144 145 <h2>Deploying a Login Application</h2> 146 147 <p>In order for this authentication mechanism to function in its entirety, a 148 login application (or resource) must be available to authenticate 149 unidentified users. It may already be the case that such an application has 150 been deployed and is available at a certain URL - if so, it should be 151 sufficient for a <code>LoginRedirectResource</code> object to be configured 152 as described above, making sure that the <code>login_url</code> actually 153 refers to the location of the existing login application, and that the 154 <code>authenticator</code> object's <code>secret_key</code> is consistent 155 with the way the existing login application has been set up.</p> 156 157 <p>However, if no existing login application (or resource) exists, one may be 158 deployed using adapter code similar to the following:</p> 159 <pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy 160 from WebStack.Resources.Login import LoginResource, LoginAuthenticator 161 162 deploy( 163 LoginResource( # This is the login application's main resource. 164 LoginAuthenticator( # This provides authentication support. 165 secret_key="horses", 166 credentials=( 167 ("badger", "abc"), 168 ("vole", "xyz"), 169 ) 170 ) 171 ), 172 address=("", 8081) 173 )</pre> 174 175 <p>The above code merely starts a login application in the 176 BaseHTTPRequestHandler environment at a specific address (which corresponds 177 to that specified in the <code>login_url</code> of the 178 <code>LoginRedirectResource</code> used above) and provides a 179 <code>LoginAuthenticator</code> object configured to use a 180 <code>secret_key</code> (which corresponds to the <code>secret_key</code> 181 used in the <code>authenticator</code> of the 182 <code>LoginRedirectResource</code> above) and some user credentials. The user 183 credentials define which users are to be recognised for applications which 184 employ this login application, along with the password details of each 185 user.</p> 186 187 <div class="WebStack"> 188 <h3>WebStack API - LoginAuthenticator Credentials</h3> 189 190 <p>When initialising a <code>LoginAuthenticator</code> object with 191 credentials, the supplied credentials object must support tests on its 192 contents of the following form:</p> 193 <pre>(username, password) in credentials</pre> 194 195 <p>In other words, the credentials object must either be a sequence of 196 username and password tuples, or it must implement the 197 <code>__contains__</code> method and accept such tuples as arguments to that 198 method.</p> 199 </div> 200 201 <h2>Anonymous Access</h2> 202 203 <p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is 204 possible to declare a particular request parameter (see 205 <code>anonymous_parameter_name</code> above) which must be present in the URL 206 used to access a particular application for the client to be given anonymous 207 access. Consequently, anonymous users are then identified specially with a 208 special username that can also be configured (see 209 <code>anonymous_username</code> above).</p> 210 211 <h2>Logout Functions</h2> 212 213 <p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is 214 possible to declare a particular request parameter (see 215 <code>logout_parameter_name</code> above) which must be present in the URL 216 used to access a particular application for the client to be logged out. A 217 special logout confirmation URL may also be configured (see 218 <code>logout_url</code> and <code>use_logout_redirect</code> above).</p> 219 </body> 220 </html>