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