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