1.1 --- a/docs/login-redirect.html Sat Apr 30 00:22:03 2005 +0000
1.2 +++ b/docs/login-redirect.html Sat Apr 30 20:31:51 2005 +0000
1.3 @@ -1,219 +1,198 @@
1.4 -<?xml version="1.0" encoding="iso-8859-1"?>
1.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.8 <html xmlns="http://www.w3.org/1999/xhtml">
1.9 <head>
1.10 <title>LoginRedirect and Login Modules</title>
1.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 + <meta name="generator"
1.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.14 <link href="styles.css" rel="stylesheet" type="text/css" />
1.15 </head>
1.16 -
1.17 <body>
1.18 <h1>LoginRedirect and Login Modules</h1>
1.19 -
1.20 -<p>The <code>LoginRedirect</code> and <code>Login</code> modules provide a
1.21 +<p>The <code>LoginRedirect</code> and <code>Login</code> modules
1.22 +provide a
1.23 "single sign-on" environment for WebStack applications. Unlike the
1.24 authenticator-only approach, each application or part of an application
1.25 utilising this mechanism must be wrapped inside a
1.26 -<code>LoginRedirectResource</code> object which determines whether a given
1.27 +<code>LoginRedirectResource</code> object which determines whether a
1.28 +given
1.29 transaction contains information identifying the application's user.</p>
1.30 -
1.31 <h2>How the Modules Work</h2>
1.32 -
1.33 -<p>When a request arrives in the application, the following things happen:</p>
1.34 +<p>When a request arrives in the application, the following things
1.35 +happen:</p>
1.36 <ol>
1.37 - <li>The <code>LoginRedirectResource</code> examines the transaction and
1.38 - attempts to find out whether it identifies a user.</li>
1.39 - <li>Should sufficient information be present in the transaction, the user
1.40 - is allowed to access the application and is identified in the normal way
1.41 - (ie. the <code>get_user</code> method on the transaction object).</li>
1.42 - <li>Otherwise, a redirect occurs to a login screen provided by a
1.43 - <code>LoginResource</code> object which then presents a login form to be
1.44 - completed by the user.</li>
1.45 - <li>The <code>LoginResource</code> object then receives the completed form
1.46 - information and verifies the identity of the user, testing the supplied
1.47 - credentials against the credentials database specified in the deployment
1.48 - of the resource.</li>
1.49 - <li>Upon successful authentication, the user is redirected back to the
1.50 - application, guarded by <code>LoginRedirectResource</code> which should
1.51 - let the user gain access.</li>
1.52 + <li>The <code>LoginRedirectResource</code> examines the transaction
1.53 +and attempts to find out whether it identifies a user.</li>
1.54 + <li>Should sufficient information be present in the transaction, the
1.55 +user is allowed to access the application and is identified in the
1.56 +normal way (ie. the <code>get_user</code> method on the transaction
1.57 +object).</li>
1.58 + <li>Otherwise, a redirect occurs to a login screen provided by a <code>LoginResource</code>
1.59 +object which then presents a login form to be completed by the user.</li>
1.60 + <li>The <code>LoginResource</code> object then receives the
1.61 +completed form information and verifies the identity of the user,
1.62 +testing the supplied credentials against the credentials database
1.63 +specified in the deployment of the resource.</li>
1.64 + <li>Upon successful authentication, the user is redirected back to
1.65 +the application, guarded by <code>LoginRedirectResource</code> which
1.66 +should let the user gain access.</li>
1.67 </ol>
1.68 -
1.69 <h2>Introducing LoginRedirectResource</h2>
1.70 -
1.71 -<p>The easiest way of introducing <code>LoginRedirectResource</code> objects
1.72 +<p>The easiest way of introducing <code>LoginRedirectResource</code>
1.73 +objects
1.74 is to do so in the adapter code, as described in <a
1.75 -href="writing-adapters.html">"Writing Adapters"</a>. The most significant
1.76 + href="writing-adapters.html">"Writing Adapters"</a>. The most
1.77 +significant
1.78 difference between deploying normal resources and
1.79 -<code>LoginRedirectResource</code> objects is the special way in which such
1.80 -objects are initialised and that they themselves contain the actual resources
1.81 +<code>LoginRedirectResource</code> objects is the special way in which
1.82 +such
1.83 +objects are initialised and that they themselves contain the actual
1.84 +resources
1.85 of the application which provide the real functionality.</p>
1.86 -
1.87 -<p>Here is what the deployment of <code>LoginRedirectResource</code> objects
1.88 +<p>Here is what the deployment of <code>LoginRedirectResource</code>
1.89 +objects
1.90 often looks like:</p>
1.91 -<pre>from WebStack.Resources.LoginRedirect import LoginRedirectResource, LoginRedirectAuthenticator
1.92 -
1.93 -deploy(
1.94 - LoginRedirectResource(
1.95 - login_url="http://localhost:8081",
1.96 - app_url="http://localhost:8080",
1.97 - resource=[some resource object which provides the real application behaviour],
1.98 - authenticator=LoginRedirectAuthenticator(secret_key="horses"),
1.99 - anonymous_parameter_name="anonymous",
1.100 - logout_parameter_name="logout"
1.101 - )
1.102 -)</pre>
1.103 -
1.104 -<p>Certain parts of the resource are configurable, according to which other
1.105 +<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>
1.106 +<p>Certain parts of the resource are configurable, according to which
1.107 +other
1.108 services may exist in or alongside the deployed application.</p>
1.109 -
1.110 <div class="WebStack">
1.111 <h3>WebStack API - LoginRedirectResource Initialisation</h3>
1.112 -
1.113 <p>The following parameters must be provided when initialising a
1.114 <code>LoginRedirectResource</code> object:</p>
1.115 <dl>
1.116 <dt><code>login_url</code></dt>
1.117 - <dd>This specifies the location of the separate login application or
1.118 - resource which presents a login screen to unidentified users and logs
1.119 - them in.</dd>
1.120 + <dd>This specifies the location of the separate login application or
1.121 +resource which presents a login screen to unidentified users and logs
1.122 +them in.</dd>
1.123 <dt><code>app_url</code></dt>
1.124 - <dd>This specifies the location of the application itself - it must
1.125 - therefore be updated according to where the application is eventually
1.126 - deployed.</dd>
1.127 + <dd>This specifies the location of the application itself - it must
1.128 +therefore be updated according to where the application is eventually
1.129 +deployed.</dd>
1.130 <dt><code>resource</code></dt>
1.131 - <dd>This provides the resource object which contains the application
1.132 - code, or at least the entry point into various parts of the application
1.133 - code.</dd>
1.134 + <dd>This provides the resource object which contains the application
1.135 +code, or at least the entry point into various parts of the application
1.136 +code.</dd>
1.137 <dt><code>authenticator</code></dt>
1.138 - <dd>This provides the authenticator object which decides whether a user
1.139 - is recognised or not. The special
1.140 - <code>LoginRedirectAuthenticator</code> is recommended and must itself
1.141 - be configured using a <code>secret_key</code> parameter which is used
1.142 - to protect user-related information exchanged over the network - the
1.143 - value provided for <code>secret_key</code> must be unguessable and kept
1.144 - secret from unauthorised individuals.</dd>
1.145 + <dd>This provides the authenticator object which decides whether a
1.146 +user is recognised or not. The special <code>LoginRedirectAuthenticator</code>
1.147 +is recommended and must itself be configured using a <code>secret_key</code>
1.148 +parameter which is used to protect user-related information exchanged
1.149 +over the network - the value provided for <code>secret_key</code> must
1.150 +be unguessable and kept secret from unauthorised individuals.</dd>
1.151 <dt><code>anonymous_parameter_name</code></dt>
1.152 - <dd>An optional parameter providing the name of a request parameter (see
1.153 - <a href="parameters.html">"Request Parameters and Uploads"</a>) which,
1.154 - if specified, permits a user to access an application without being
1.155 - formally identified. If omitted, all users will be required to identify
1.156 - themselves explicitly.</dd>
1.157 + <dd>An optional parameter providing the name of a request parameter
1.158 +(see <a href="parameters.html">"Request Parameters and Uploads"</a>)
1.159 +which, if specified, permits a user to access an application without
1.160 +being formally identified. If omitted, all users will be required to
1.161 +identify themselves explicitly.</dd>
1.162 <dt><code>anonymous_username</code></dt>
1.163 - <dd>An optional parameter providing the name given to anonymous users
1.164 - which is returned when a transaction's <code>get_user</code> method is
1.165 - called. By default, <code>anonymous</code> is used for such users.</dd>
1.166 + <dd>An optional parameter providing the name given to anonymous users
1.167 +which is returned when a transaction's <code>get_user</code> method is
1.168 +called. By default, <code>anonymous</code> is used for such users.</dd>
1.169 <dt><code>logout_parameter_name</code></dt>
1.170 - <dd>An optional parameter providing the name of a request parameter
1.171 - which, if specified, permits a user to log out of an application. If
1.172 - omitted, no means of logging out will be available, although deleting
1.173 - browser cookies will probably have the desired effect.</dd>
1.174 + <dd>An optional parameter providing the name of a request parameter
1.175 +which, if specified, permits a user to log out of an application. If
1.176 +omitted, no means of logging out will be available, although deleting
1.177 +browser cookies will probably have the desired effect.</dd>
1.178 <dt><code>logout_url</code></dt>
1.179 - <dd>An optional parameter which indicates the location of the resource
1.180 - visited when a user logs out. By default, the location is a path to the
1.181 - root resource in the server environment of the application.</dd>
1.182 + <dd>An optional parameter which indicates the location of the
1.183 +resource visited when a user logs out. By default, the location is a
1.184 +path to the root resource in the server environment of the application.</dd>
1.185 <dt><code>use_logout_redirect</code></dt>
1.186 - <dd>An optional parameter which determines whether users logging out of
1.187 - an application will be redirected to the <code>logout_url</code> or
1.188 - not. By default, users are redirected, but if a false value is given
1.189 - for this parameter, a simple page is presented to the user informing
1.190 - them of the situation - it is recommended that a subclass of
1.191 - <code>LoginRedirectResource</code> be employed should more informative
1.192 - pages be required.</dd>
1.193 + <dd>An optional parameter which determines whether users logging out
1.194 +of an application will be redirected to the <code>logout_url</code> or
1.195 +not. By default, users are redirected, but if a false value is given
1.196 +for this parameter, a simple page is presented to the user informing
1.197 +them of the situation - it is recommended that a subclass of <code>LoginRedirectResource</code>
1.198 +be employed should more informative pages be required.</dd>
1.199 </dl>
1.200 </div>
1.201 -
1.202 -<h3>Redirection From/To the Application</h3>
1.203 -
1.204 -<p>Some server/framework environments do not permit automatic redirection
1.205 -back to the application, notably Apache/mod_python. In such cases, a success
1.206 -screen is presented to the user with a link to the application they were
1.207 +<h3>Redirection from/to the Application</h3>
1.208 +<p>Some server/framework environments do not permit automatic
1.209 +redirection
1.210 +back to the application, notably Apache/mod_python. In such cases, a
1.211 +success
1.212 +screen is presented to the user with a link to the application they
1.213 +were
1.214 attempting to access.</p>
1.215 -
1.216 <h3>The Role of Authenticators</h3>
1.217 -
1.218 -<p>In this mechanism, authenticators are employed, but only to verify the
1.219 +<p>In this mechanism, authenticators are employed, but only to verify
1.220 +the
1.221 credentials of users when <code>LoginResource</code> or
1.222 -<code>LoginRedirectResource</code> objects are accessed. Although it should
1.223 +<code>LoginRedirectResource</code> objects are accessed. Although it
1.224 +should
1.225 be possible to reuse <a href="authenticators.html">application-wide
1.226 authenticator</a> classes in conjunction with <code>LoginResource</code>,
1.227 such classes will not provide the additional functionality required to
1.228 support the "single sign-on" aspects of this mechanism - mixing in such
1.229 -classes with <code>LoginAuthenticator</code> may provide a solution to this
1.230 +classes with <code>LoginAuthenticator</code> may provide a solution to
1.231 +this
1.232 issue, however.</p>
1.233 -
1.234 <h2>Deploying a Login Application</h2>
1.235 -
1.236 -<p>In order for this authentication mechanism to function in its entirety, a
1.237 +<p>In order for this authentication mechanism to function in its
1.238 +entirety, a
1.239 login application (or resource) must be available to authenticate
1.240 -unidentified users. It may already be the case that such an application has
1.241 +unidentified users. It may already be the case that such an application
1.242 +has
1.243 been deployed and is available at a certain URL - if so, it should be
1.244 -sufficient for a <code>LoginRedirectResource</code> object to be configured
1.245 -as described above, making sure that the <code>login_url</code> actually
1.246 +sufficient for a <code>LoginRedirectResource</code> object to be
1.247 +configured
1.248 +as described above, making sure that the <code>login_url</code>
1.249 +actually
1.250 refers to the location of the existing login application, and that the
1.251 -<code>authenticator</code> object's <code>secret_key</code> is consistent
1.252 +<code>authenticator</code> object's <code>secret_key</code> is
1.253 +consistent
1.254 with the way the existing login application has been set up.</p>
1.255 -
1.256 -<p>However, if no existing login application (or resource) exists, one may be
1.257 +<p>However, if no existing login application (or resource) exists, one
1.258 +may be
1.259 deployed using adapter code similar to the following:</p>
1.260 -<pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy
1.261 -from WebStack.Resources.Login import LoginResource, LoginAuthenticator
1.262 -
1.263 -deploy(
1.264 - LoginResource( # This is the login application's main resource.
1.265 - LoginAuthenticator( # This provides authentication support.
1.266 - secret_key="horses",
1.267 - credentials=(
1.268 - ("badger", "abc"),
1.269 - ("vole", "xyz"),
1.270 - )
1.271 - )
1.272 - ),
1.273 - address=("", 8081)
1.274 -)</pre>
1.275 -
1.276 +<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>
1.277 <p>The above code merely starts a login application in the
1.278 -BaseHTTPRequestHandler environment at a specific address (which corresponds
1.279 +BaseHTTPRequestHandler environment at a specific address (which
1.280 +corresponds
1.281 to that specified in the <code>login_url</code> of the
1.282 <code>LoginRedirectResource</code> used above) and provides a
1.283 <code>LoginAuthenticator</code> object configured to use a
1.284 <code>secret_key</code> (which corresponds to the <code>secret_key</code>
1.285 used in the <code>authenticator</code> of the
1.286 -<code>LoginRedirectResource</code> above) and some user credentials. The user
1.287 -credentials define which users are to be recognised for applications which
1.288 +<code>LoginRedirectResource</code> above) and some user credentials.
1.289 +The user
1.290 +credentials define which users are to be recognised for applications
1.291 +which
1.292 employ this login application, along with the password details of each
1.293 user.</p>
1.294 -
1.295 <div class="WebStack">
1.296 <h3>WebStack API - LoginAuthenticator Credentials</h3>
1.297 -
1.298 <p>When initialising a <code>LoginAuthenticator</code> object with
1.299 credentials, the supplied credentials object must support tests on its
1.300 contents of the following form:</p>
1.301 <pre>(username, password) in credentials</pre>
1.302 -
1.303 <p>In other words, the credentials object must either be a sequence of
1.304 username and password tuples, or it must implement the
1.305 -<code>__contains__</code> method and accept such tuples as arguments to that
1.306 +<code>__contains__</code> method and accept such tuples as arguments to
1.307 +that
1.308 method.</p>
1.309 </div>
1.310 -
1.311 <h2>Anonymous Access</h2>
1.312 -
1.313 -<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
1.314 +<p>With the <code>LoginRedirect</code> and <code>Login</code>
1.315 +modules, it is
1.316 possible to declare a particular request parameter (see
1.317 -<code>anonymous_parameter_name</code> above) which must be present in the URL
1.318 -used to access a particular application for the client to be given anonymous
1.319 -access. Consequently, anonymous users are then identified specially with a
1.320 +<code>anonymous_parameter_name</code> above) which must be present in
1.321 +the URL
1.322 +used to access a particular application for the client to be given
1.323 +anonymous
1.324 +access. Consequently, anonymous users are then identified specially
1.325 +with a
1.326 special username that can also be configured (see
1.327 <code>anonymous_username</code> above).</p>
1.328 -
1.329 <h2>Logout Functions</h2>
1.330 -
1.331 -<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
1.332 +<p>With the <code>LoginRedirect</code> and <code>Login</code>
1.333 +modules, it is
1.334 possible to declare a particular request parameter (see
1.335 -<code>logout_parameter_name</code> above) which must be present in the URL
1.336 -used to access a particular application for the client to be logged out. A
1.337 +<code>logout_parameter_name</code> above) which must be present in the
1.338 +URL
1.339 +used to access a particular application for the client to be logged
1.340 +out. A
1.341 special logout confirmation URL may also be configured (see
1.342 <code>logout_url</code> and <code>use_logout_redirect</code> above).</p>
1.343 </body>