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