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