WebStack

Annotated docs/login-redirect.html

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