1.1 --- a/docs/SESSION.txt Sat Apr 30 00:22:03 2005 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,27 +0,0 @@
1.4 -Session Support in WebStack
1.5 ----------------------------
1.6 -
1.7 -Various frameworks do not support sessions. In order to provide primitive
1.8 -support for sessions within WebStack upon such frameworks, the
1.9 -WebStack.Helpers.Session module is used to provide a simple file-based session
1.10 -store. It is necessary to create a directory called WebStack-sessions in a
1.11 -particular location for the session store to function, and the location depends
1.12 -on the framework as summarised in the following table.
1.13 -
1.14 -Framework Location
1.15 ---------- --------
1.16 -BaseHTTPRequestHandler The directory where the server is run.
1.17 -CGI The directory where the handler resides.
1.18 -mod_python The server root (eg. /usr/local/apache2).
1.19 -Twisted The directory where the server is run.
1.20 -
1.21 -Note that the WebStack-sessions directory must have the appropriate ownership
1.22 -and privileges necessary for the server/framework to write session files into
1.23 -it.
1.24 -
1.25 -Unsupported Frameworks and Framework Issues
1.26 --------------------------------------------
1.27 -
1.28 -Webware 0.8.1 has problems creating sessions and is therefore not supported.
1.29 -Webware releases later than 0.8.1 (at least until the 2004-02-06 CVS snapshot
1.30 -used for testing) do not support session detection or expiry correctly.
2.1 --- a/docs/authenticators.html Sat Apr 30 00:22:03 2005 +0000
2.2 +++ b/docs/authenticators.html Sat Apr 30 20:31:51 2005 +0000
2.3 @@ -1,101 +1,69 @@
2.4 -<?xml version="1.0" encoding="iso-8859-1"?>
2.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.8 <html xmlns="http://www.w3.org/1999/xhtml">
2.9 <head>
2.10 <title>Application-Wide Authenticators</title>
2.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.12 + <meta name="generator"
2.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.14 <link href="styles.css" rel="stylesheet" type="text/css" />
2.15 </head>
2.16 -
2.17 <body>
2.18 <h1>Application-Wide Authenticators</h1>
2.19 -
2.20 <p>Authenticators are special classes which can, in conjunction with
2.21 -mechanisms in the server environment, judge whether a user of an application
2.22 +mechanisms in the server environment, judge whether a user of an
2.23 +application
2.24 is recognised or not. The process of using authenticators is as follows:</p>
2.25 <ol>
2.26 - <li>Set up authentication in the server environment or framework in which
2.27 - the application is to be deployed.</li>
2.28 + <li>Set up authentication in the server environment or framework in
2.29 +which the application is to be deployed.</li>
2.30 <li>Introduce an authenticator class in the application.</li>
2.31 </ol>
2.32 -
2.33 <h2>Setting Up Authentication</h2>
2.34 -
2.35 -<p>The exact details of configuring authentication mechanisms in each server
2.36 -environment may vary substantially. For example, Apache environments require
2.37 -that <code>Auth</code> directives be specified in the Apache configuration
2.38 -files (see <code>docs/ModPython/NOTES.txt</code>); in Zope environments,
2.39 -protected folders can be defined to hold the application when deployed (see
2.40 +<p>The exact details of configuring authentication mechanisms in each
2.41 +server
2.42 +environment may vary substantially. For example, Apache environments
2.43 +require
2.44 +that <code>Auth</code> directives be specified in the Apache
2.45 +configuration
2.46 +files (see <code>docs/ModPython/NOTES.txt</code>); in Zope
2.47 +environments,
2.48 +protected folders can be defined to hold the application when deployed
2.49 +(see
2.50 <code>docs/Zope/NOTES.txt</code>).</p>
2.51 -
2.52 <h2>Defining an Authenticator</h2>
2.53 -
2.54 -<p>An authenticator must be defined within your application in order to make
2.55 +<p>An authenticator must be defined within your application in order to
2.56 +make
2.57 decisions about users who have presented their credentials; this
2.58 -authenticator will respond with a decision when prompted by the server or
2.59 -underlying framework, either allowing or denying access for the user whose
2.60 +authenticator will respond with a decision when prompted by the server
2.61 +or
2.62 +underlying framework, either allowing or denying access for the user
2.63 +whose
2.64 identity has been presented to the server/framework.</p>
2.65 -
2.66 <p>The code for an authenticator usually looks like this:</p>
2.67 -<pre>class MyAuthenticator:
2.68 -
2.69 - "This is an authenticator - something which decides whether a user is known to the application."
2.70 -
2.71 - def authenticate(self, trans):
2.72 - user = trans.get_user()
2.73 - [Make a decision about the validity of the user.]
2.74 - [Return a true value if the user is allowed to access the application.]
2.75 - [Return a false value if the user is not recognised or allowed to access the application.]
2.76 -
2.77 - def get_auth_type(self):
2.78 - "This method returns 'Basic' in most deployments."
2.79 - return "Basic"
2.80 -
2.81 - def get_realm(self):
2.82 - "This method returns something to distinguish this authentication mechanism from others."
2.83 - return "MyRealm"</pre>
2.84 -
2.85 -<p>In this mechanism, authenticators rely on authentication information from
2.86 -the server/framework and have a "global" effect on access to the application.
2.87 -However, it is always possible to test the user identity later on and to
2.88 -change the way an application behaves accordingly.</p>
2.89 -
2.90 -<div class="WebStack">
2.91 -<h3>WebStack API - User Identity</h3>
2.92 -
2.93 -<p>Transaction objects have the following methods for inspecting and
2.94 -redefining the identity of users:</p>
2.95 -<dl>
2.96 - <dt><code>get_user</code></dt>
2.97 - <dd>This gets the name of the user attempting to access the
2.98 - application.</dd>
2.99 - <dt><code>set_user</code></dt>
2.100 - <dd>This sets the name of the user, thus affecting subsequent calls to
2.101 - <code>get_user</code>, allowing certain parts of an application to view
2.102 - users according to other criteria than their basic username - for
2.103 - example, one might use <code>set_user</code> to redefine each user's
2.104 - identity in terms of the role that user may have in an application.</dd>
2.105 -</dl>
2.106 -</div>
2.107 -
2.108 +<pre>class MyAuthenticator:<br /><br /> "This is an authenticator - something which decides whether a user is known to the application."<br /><br /> def authenticate(self, trans):<br /> user = trans.get_user()<br /> [Make a decision about the validity of the user.]<br /> [Return a true value if the user is allowed to access the application.]<br /> [Return a false value if the user is not recognised or allowed to access the application.]<br /><br /> def get_auth_type(self):<br /> "This method returns 'Basic' in most deployments."<br /> return "Basic"<br /><br /> def get_realm(self):<br /> "This method returns something to distinguish this authentication mechanism from others."<br /> return "MyRealm"</pre>
2.109 +<p>In this mechanism, authenticators rely on authentication information
2.110 +from
2.111 +the server environment and have a "global" effect on access to the
2.112 +application.
2.113 +However, it is always possible to test the user identity later on and
2.114 +to
2.115 +change the way an application behaves accordingly - see <a
2.116 + href="users.html">"Users and Authentication"</a> for more information.</p>
2.117 <h2>Introducing an Authenticator</h2>
2.118 -
2.119 <p>Authenticator objects are created in the adapter code - see <a
2.120 -href="writing-adapters.html">"Writing Adapters"</a> for more information.</p>
2.121 -
2.122 + href="writing-adapters.html">"Writing Adapters"</a> for more
2.123 +information.</p>
2.124 <h2>Anonymous Access</h2>
2.125 -
2.126 -<p>With application-wide authenticators, anonymous access to resources and
2.127 -applications can be difficult to permit alongside access by specific users,
2.128 +<p>With application-wide authenticators, anonymous access to resources
2.129 +and
2.130 +applications can be difficult to permit alongside access by specific
2.131 +users,
2.132 mostly because servers and frameworks which employ HTTP authentication
2.133 schemes do so globally for a given application.</p>
2.134 -
2.135 <h2>Logout Functions</h2>
2.136 -
2.137 <p>With application-wide authenticators, a logout function may not be
2.138 available if the server/framework has been configured to use HTTP
2.139 -authentication schemes, mainly because no logout mechanism generally exists
2.140 +authentication schemes, mainly because no logout mechanism generally
2.141 +exists
2.142 for such schemes.</p>
2.143 </body>
2.144 </html>
3.1 --- a/docs/cookies.html Sat Apr 30 00:22:03 2005 +0000
3.2 +++ b/docs/cookies.html Sat Apr 30 20:31:51 2005 +0000
3.3 @@ -19,9 +19,17 @@
3.4 stored in a cookie and the type of that information (it must be a plain
3.5 Python string), the mechanism is useful for identifying users or
3.6 remembering simple things about the operations that the user has been
3.7 -performing. Some applications use cookies to remember the state
3.8 -of their user interfaces, such as which parts of a navigational
3.9 -menu have been opened by the user, for example.</p>
3.10 +performing. Some uses include:</p>
3.11 +<ul>
3.12 + <li>The use of cookies to remember the state
3.13 +of user interfaces, such as which parts of a navigational
3.14 +menu have been opened by the user.</li>
3.15 + <li>The identification of users, although since cookie information is
3.16 +transmitted back to the user potentially using an insecure network
3.17 +communication, it is usually necessary to encrypt or encode sensitive
3.18 +information which would identify a user or let an eavesdropper pretend
3.19 +to be that user in their own communications with an application.</li>
3.20 +</ul>
3.21 <div class="WebStack">
3.22 <h3>WebStack API - Using Cookies</h3>
3.23 <p>The <a
4.1 --- a/docs/design.html Sat Apr 30 00:22:03 2005 +0000
4.2 +++ b/docs/design.html Sat Apr 30 20:31:51 2005 +0000
4.3 @@ -11,7 +11,7 @@
4.4 <h1>Application Design Considerations</h1>
4.5 <p>When writing an application, we
4.6 must try and cover the three activities mentioned in our overview of
4.7 -what a simple application looks like:</p>
4.8 +what a simple resource looks like:</p>
4.9 <ol>
4.10 <li>Examine the transaction, decide what the user wants to do.</li>
4.11 <li>Perform some kind of action with the information supplied.</li>
5.1 --- a/docs/encodings.html Sat Apr 30 00:22:03 2005 +0000
5.2 +++ b/docs/encodings.html Sat Apr 30 20:31:51 2005 +0000
5.3 @@ -12,10 +12,11 @@
5.4 Python's Unicode objects as much as possible. However, there are a
5.5 number of places where plain Python strings can be involved:</p>
5.6 <ul>
5.7 - <li>When <a href="parameters.html">inspecting request parameters</a>.</li>
5.8 - <li>When <a href="responses.html">sending output in a response</a>.</li>
5.9 - <li>When <a href="parameters.html">receiving uploaded content</a>.</li>
5.10 - <li>When <a href="state.html">accessing cookie information</a>.</li>
5.11 + <li><a href="parameters.html">Inspecting request parameters</a></li>
5.12 + <li><a href="responses.html">Sending output in a response</a></li>
5.13 + <li><a href="parameters.html">Receiving uploaded content</a></li>
5.14 + <li><a href="state.html">Accessing cookie information</a></li>
5.15 + <li><a href="sessions.html">Accessing session information</a></li>
5.16 </ul>
5.17 <p>When Web pages (and other types of content) are sent to and from
5.18 users of your application, the text will be in some kind of character
6.1 --- a/docs/login-redirect.html Sat Apr 30 00:22:03 2005 +0000
6.2 +++ b/docs/login-redirect.html Sat Apr 30 20:31:51 2005 +0000
6.3 @@ -1,219 +1,198 @@
6.4 -<?xml version="1.0" encoding="iso-8859-1"?>
6.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
6.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.8 <html xmlns="http://www.w3.org/1999/xhtml">
6.9 <head>
6.10 <title>LoginRedirect and Login Modules</title>
6.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.12 + <meta name="generator"
6.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.14 <link href="styles.css" rel="stylesheet" type="text/css" />
6.15 </head>
6.16 -
6.17 <body>
6.18 <h1>LoginRedirect and Login Modules</h1>
6.19 -
6.20 -<p>The <code>LoginRedirect</code> and <code>Login</code> modules provide a
6.21 +<p>The <code>LoginRedirect</code> and <code>Login</code> modules
6.22 +provide a
6.23 "single sign-on" environment for WebStack applications. Unlike the
6.24 authenticator-only approach, each application or part of an application
6.25 utilising this mechanism must be wrapped inside a
6.26 -<code>LoginRedirectResource</code> object which determines whether a given
6.27 +<code>LoginRedirectResource</code> object which determines whether a
6.28 +given
6.29 transaction contains information identifying the application's user.</p>
6.30 -
6.31 <h2>How the Modules Work</h2>
6.32 -
6.33 -<p>When a request arrives in the application, the following things happen:</p>
6.34 +<p>When a request arrives in the application, the following things
6.35 +happen:</p>
6.36 <ol>
6.37 - <li>The <code>LoginRedirectResource</code> examines the transaction and
6.38 - attempts to find out whether it identifies a user.</li>
6.39 - <li>Should sufficient information be present in the transaction, the user
6.40 - is allowed to access the application and is identified in the normal way
6.41 - (ie. the <code>get_user</code> method on the transaction object).</li>
6.42 - <li>Otherwise, a redirect occurs to a login screen provided by a
6.43 - <code>LoginResource</code> object which then presents a login form to be
6.44 - completed by the user.</li>
6.45 - <li>The <code>LoginResource</code> object then receives the completed form
6.46 - information and verifies the identity of the user, testing the supplied
6.47 - credentials against the credentials database specified in the deployment
6.48 - of the resource.</li>
6.49 - <li>Upon successful authentication, the user is redirected back to the
6.50 - application, guarded by <code>LoginRedirectResource</code> which should
6.51 - let the user gain access.</li>
6.52 + <li>The <code>LoginRedirectResource</code> examines the transaction
6.53 +and attempts to find out whether it identifies a user.</li>
6.54 + <li>Should sufficient information be present in the transaction, the
6.55 +user is allowed to access the application and is identified in the
6.56 +normal way (ie. the <code>get_user</code> method on the transaction
6.57 +object).</li>
6.58 + <li>Otherwise, a redirect occurs to a login screen provided by a <code>LoginResource</code>
6.59 +object which then presents a login form to be completed by the user.</li>
6.60 + <li>The <code>LoginResource</code> object then receives the
6.61 +completed form information and verifies the identity of the user,
6.62 +testing the supplied credentials against the credentials database
6.63 +specified in the deployment of the resource.</li>
6.64 + <li>Upon successful authentication, the user is redirected back to
6.65 +the application, guarded by <code>LoginRedirectResource</code> which
6.66 +should let the user gain access.</li>
6.67 </ol>
6.68 -
6.69 <h2>Introducing LoginRedirectResource</h2>
6.70 -
6.71 -<p>The easiest way of introducing <code>LoginRedirectResource</code> objects
6.72 +<p>The easiest way of introducing <code>LoginRedirectResource</code>
6.73 +objects
6.74 is to do so in the adapter code, as described in <a
6.75 -href="writing-adapters.html">"Writing Adapters"</a>. The most significant
6.76 + href="writing-adapters.html">"Writing Adapters"</a>. The most
6.77 +significant
6.78 difference between deploying normal resources and
6.79 -<code>LoginRedirectResource</code> objects is the special way in which such
6.80 -objects are initialised and that they themselves contain the actual resources
6.81 +<code>LoginRedirectResource</code> objects is the special way in which
6.82 +such
6.83 +objects are initialised and that they themselves contain the actual
6.84 +resources
6.85 of the application which provide the real functionality.</p>
6.86 -
6.87 -<p>Here is what the deployment of <code>LoginRedirectResource</code> objects
6.88 +<p>Here is what the deployment of <code>LoginRedirectResource</code>
6.89 +objects
6.90 often looks like:</p>
6.91 -<pre>from WebStack.Resources.LoginRedirect import LoginRedirectResource, LoginRedirectAuthenticator
6.92 -
6.93 -deploy(
6.94 - LoginRedirectResource(
6.95 - login_url="http://localhost:8081",
6.96 - app_url="http://localhost:8080",
6.97 - resource=[some resource object which provides the real application behaviour],
6.98 - authenticator=LoginRedirectAuthenticator(secret_key="horses"),
6.99 - anonymous_parameter_name="anonymous",
6.100 - logout_parameter_name="logout"
6.101 - )
6.102 -)</pre>
6.103 -
6.104 -<p>Certain parts of the resource are configurable, according to which other
6.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>
6.106 +<p>Certain parts of the resource are configurable, according to which
6.107 +other
6.108 services may exist in or alongside the deployed application.</p>
6.109 -
6.110 <div class="WebStack">
6.111 <h3>WebStack API - LoginRedirectResource Initialisation</h3>
6.112 -
6.113 <p>The following parameters must be provided when initialising a
6.114 <code>LoginRedirectResource</code> object:</p>
6.115 <dl>
6.116 <dt><code>login_url</code></dt>
6.117 - <dd>This specifies the location of the separate login application or
6.118 - resource which presents a login screen to unidentified users and logs
6.119 - them in.</dd>
6.120 + <dd>This specifies the location of the separate login application or
6.121 +resource which presents a login screen to unidentified users and logs
6.122 +them in.</dd>
6.123 <dt><code>app_url</code></dt>
6.124 - <dd>This specifies the location of the application itself - it must
6.125 - therefore be updated according to where the application is eventually
6.126 - deployed.</dd>
6.127 + <dd>This specifies the location of the application itself - it must
6.128 +therefore be updated according to where the application is eventually
6.129 +deployed.</dd>
6.130 <dt><code>resource</code></dt>
6.131 - <dd>This provides the resource object which contains the application
6.132 - code, or at least the entry point into various parts of the application
6.133 - code.</dd>
6.134 + <dd>This provides the resource object which contains the application
6.135 +code, or at least the entry point into various parts of the application
6.136 +code.</dd>
6.137 <dt><code>authenticator</code></dt>
6.138 - <dd>This provides the authenticator object which decides whether a user
6.139 - is recognised or not. The special
6.140 - <code>LoginRedirectAuthenticator</code> is recommended and must itself
6.141 - be configured using a <code>secret_key</code> parameter which is used
6.142 - to protect user-related information exchanged over the network - the
6.143 - value provided for <code>secret_key</code> must be unguessable and kept
6.144 - secret from unauthorised individuals.</dd>
6.145 + <dd>This provides the authenticator object which decides whether a
6.146 +user is recognised or not. The special <code>LoginRedirectAuthenticator</code>
6.147 +is recommended and must itself be configured using a <code>secret_key</code>
6.148 +parameter which is used to protect user-related information exchanged
6.149 +over the network - the value provided for <code>secret_key</code> must
6.150 +be unguessable and kept secret from unauthorised individuals.</dd>
6.151 <dt><code>anonymous_parameter_name</code></dt>
6.152 - <dd>An optional parameter providing the name of a request parameter (see
6.153 - <a href="parameters.html">"Request Parameters and Uploads"</a>) which,
6.154 - if specified, permits a user to access an application without being
6.155 - formally identified. If omitted, all users will be required to identify
6.156 - themselves explicitly.</dd>
6.157 + <dd>An optional parameter providing the name of a request parameter
6.158 +(see <a href="parameters.html">"Request Parameters and Uploads"</a>)
6.159 +which, if specified, permits a user to access an application without
6.160 +being formally identified. If omitted, all users will be required to
6.161 +identify themselves explicitly.</dd>
6.162 <dt><code>anonymous_username</code></dt>
6.163 - <dd>An optional parameter providing the name given to anonymous users
6.164 - which is returned when a transaction's <code>get_user</code> method is
6.165 - called. By default, <code>anonymous</code> is used for such users.</dd>
6.166 + <dd>An optional parameter providing the name given to anonymous users
6.167 +which is returned when a transaction's <code>get_user</code> method is
6.168 +called. By default, <code>anonymous</code> is used for such users.</dd>
6.169 <dt><code>logout_parameter_name</code></dt>
6.170 - <dd>An optional parameter providing the name of a request parameter
6.171 - which, if specified, permits a user to log out of an application. If
6.172 - omitted, no means of logging out will be available, although deleting
6.173 - browser cookies will probably have the desired effect.</dd>
6.174 + <dd>An optional parameter providing the name of a request parameter
6.175 +which, if specified, permits a user to log out of an application. If
6.176 +omitted, no means of logging out will be available, although deleting
6.177 +browser cookies will probably have the desired effect.</dd>
6.178 <dt><code>logout_url</code></dt>
6.179 - <dd>An optional parameter which indicates the location of the resource
6.180 - visited when a user logs out. By default, the location is a path to the
6.181 - root resource in the server environment of the application.</dd>
6.182 + <dd>An optional parameter which indicates the location of the
6.183 +resource visited when a user logs out. By default, the location is a
6.184 +path to the root resource in the server environment of the application.</dd>
6.185 <dt><code>use_logout_redirect</code></dt>
6.186 - <dd>An optional parameter which determines whether users logging out of
6.187 - an application will be redirected to the <code>logout_url</code> or
6.188 - not. By default, users are redirected, but if a false value is given
6.189 - for this parameter, a simple page is presented to the user informing
6.190 - them of the situation - it is recommended that a subclass of
6.191 - <code>LoginRedirectResource</code> be employed should more informative
6.192 - pages be required.</dd>
6.193 + <dd>An optional parameter which determines whether users logging out
6.194 +of an application will be redirected to the <code>logout_url</code> or
6.195 +not. By default, users are redirected, but if a false value is given
6.196 +for this parameter, a simple page is presented to the user informing
6.197 +them of the situation - it is recommended that a subclass of <code>LoginRedirectResource</code>
6.198 +be employed should more informative pages be required.</dd>
6.199 </dl>
6.200 </div>
6.201 -
6.202 -<h3>Redirection From/To the Application</h3>
6.203 -
6.204 -<p>Some server/framework environments do not permit automatic redirection
6.205 -back to the application, notably Apache/mod_python. In such cases, a success
6.206 -screen is presented to the user with a link to the application they were
6.207 +<h3>Redirection from/to the Application</h3>
6.208 +<p>Some server/framework environments do not permit automatic
6.209 +redirection
6.210 +back to the application, notably Apache/mod_python. In such cases, a
6.211 +success
6.212 +screen is presented to the user with a link to the application they
6.213 +were
6.214 attempting to access.</p>
6.215 -
6.216 <h3>The Role of Authenticators</h3>
6.217 -
6.218 -<p>In this mechanism, authenticators are employed, but only to verify the
6.219 +<p>In this mechanism, authenticators are employed, but only to verify
6.220 +the
6.221 credentials of users when <code>LoginResource</code> or
6.222 -<code>LoginRedirectResource</code> objects are accessed. Although it should
6.223 +<code>LoginRedirectResource</code> objects are accessed. Although it
6.224 +should
6.225 be possible to reuse <a href="authenticators.html">application-wide
6.226 authenticator</a> classes in conjunction with <code>LoginResource</code>,
6.227 such classes will not provide the additional functionality required to
6.228 support the "single sign-on" aspects of this mechanism - mixing in such
6.229 -classes with <code>LoginAuthenticator</code> may provide a solution to this
6.230 +classes with <code>LoginAuthenticator</code> may provide a solution to
6.231 +this
6.232 issue, however.</p>
6.233 -
6.234 <h2>Deploying a Login Application</h2>
6.235 -
6.236 -<p>In order for this authentication mechanism to function in its entirety, a
6.237 +<p>In order for this authentication mechanism to function in its
6.238 +entirety, a
6.239 login application (or resource) must be available to authenticate
6.240 -unidentified users. It may already be the case that such an application has
6.241 +unidentified users. It may already be the case that such an application
6.242 +has
6.243 been deployed and is available at a certain URL - if so, it should be
6.244 -sufficient for a <code>LoginRedirectResource</code> object to be configured
6.245 -as described above, making sure that the <code>login_url</code> actually
6.246 +sufficient for a <code>LoginRedirectResource</code> object to be
6.247 +configured
6.248 +as described above, making sure that the <code>login_url</code>
6.249 +actually
6.250 refers to the location of the existing login application, and that the
6.251 -<code>authenticator</code> object's <code>secret_key</code> is consistent
6.252 +<code>authenticator</code> object's <code>secret_key</code> is
6.253 +consistent
6.254 with the way the existing login application has been set up.</p>
6.255 -
6.256 -<p>However, if no existing login application (or resource) exists, one may be
6.257 +<p>However, if no existing login application (or resource) exists, one
6.258 +may be
6.259 deployed using adapter code similar to the following:</p>
6.260 -<pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy
6.261 -from WebStack.Resources.Login import LoginResource, LoginAuthenticator
6.262 -
6.263 -deploy(
6.264 - LoginResource( # This is the login application's main resource.
6.265 - LoginAuthenticator( # This provides authentication support.
6.266 - secret_key="horses",
6.267 - credentials=(
6.268 - ("badger", "abc"),
6.269 - ("vole", "xyz"),
6.270 - )
6.271 - )
6.272 - ),
6.273 - address=("", 8081)
6.274 -)</pre>
6.275 -
6.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>
6.277 <p>The above code merely starts a login application in the
6.278 -BaseHTTPRequestHandler environment at a specific address (which corresponds
6.279 +BaseHTTPRequestHandler environment at a specific address (which
6.280 +corresponds
6.281 to that specified in the <code>login_url</code> of the
6.282 <code>LoginRedirectResource</code> used above) and provides a
6.283 <code>LoginAuthenticator</code> object configured to use a
6.284 <code>secret_key</code> (which corresponds to the <code>secret_key</code>
6.285 used in the <code>authenticator</code> of the
6.286 -<code>LoginRedirectResource</code> above) and some user credentials. The user
6.287 -credentials define which users are to be recognised for applications which
6.288 +<code>LoginRedirectResource</code> above) and some user credentials.
6.289 +The user
6.290 +credentials define which users are to be recognised for applications
6.291 +which
6.292 employ this login application, along with the password details of each
6.293 user.</p>
6.294 -
6.295 <div class="WebStack">
6.296 <h3>WebStack API - LoginAuthenticator Credentials</h3>
6.297 -
6.298 <p>When initialising a <code>LoginAuthenticator</code> object with
6.299 credentials, the supplied credentials object must support tests on its
6.300 contents of the following form:</p>
6.301 <pre>(username, password) in credentials</pre>
6.302 -
6.303 <p>In other words, the credentials object must either be a sequence of
6.304 username and password tuples, or it must implement the
6.305 -<code>__contains__</code> method and accept such tuples as arguments to that
6.306 +<code>__contains__</code> method and accept such tuples as arguments to
6.307 +that
6.308 method.</p>
6.309 </div>
6.310 -
6.311 <h2>Anonymous Access</h2>
6.312 -
6.313 -<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
6.314 +<p>With the <code>LoginRedirect</code> and <code>Login</code>
6.315 +modules, it is
6.316 possible to declare a particular request parameter (see
6.317 -<code>anonymous_parameter_name</code> above) which must be present in the URL
6.318 -used to access a particular application for the client to be given anonymous
6.319 -access. Consequently, anonymous users are then identified specially with a
6.320 +<code>anonymous_parameter_name</code> above) which must be present in
6.321 +the URL
6.322 +used to access a particular application for the client to be given
6.323 +anonymous
6.324 +access. Consequently, anonymous users are then identified specially
6.325 +with a
6.326 special username that can also be configured (see
6.327 <code>anonymous_username</code> above).</p>
6.328 -
6.329 <h2>Logout Functions</h2>
6.330 -
6.331 -<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
6.332 +<p>With the <code>LoginRedirect</code> and <code>Login</code>
6.333 +modules, it is
6.334 possible to declare a particular request parameter (see
6.335 -<code>logout_parameter_name</code> above) which must be present in the URL
6.336 -used to access a particular application for the client to be logged out. A
6.337 +<code>logout_parameter_name</code> above) which must be present in the
6.338 +URL
6.339 +used to access a particular application for the client to be logged
6.340 +out. A
6.341 special logout confirmation URL may also be configured (see
6.342 <code>logout_url</code> and <code>use_logout_redirect</code> above).</p>
6.343 </body>
7.1 --- a/docs/securing.html Sat Apr 30 00:22:03 2005 +0000
7.2 +++ b/docs/securing.html Sat Apr 30 20:31:51 2005 +0000
7.3 @@ -1,32 +1,28 @@
7.4 -<?xml version="1.0" encoding="iso-8859-1"?>
7.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
7.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.8 <html xmlns="http://www.w3.org/1999/xhtml">
7.9 <head>
7.10 <title>Securing a WebStack Application</title>
7.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.12 + <meta name="generator"
7.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.14 <link href="styles.css" rel="stylesheet" type="text/css" />
7.15 </head>
7.16 -
7.17 <body>
7.18 <h1>Securing a WebStack Application</h1>
7.19 -
7.20 -<p>Making sure that Web applications are "secure" involves many different
7.21 -aspects of application design, deployment and administration. This document
7.22 -covers only the usage of the authentication features of the WebStack API.</p>
7.23 -
7.24 +<p>Making sure that Web applications are "secure" involves many
7.25 +different
7.26 +aspects of application design, deployment and administration. This
7.27 +guide currently only covers the usage of the authentication features of
7.28 +the WebStack API.</p>
7.29 <h2>Authentication in WebStack</h2>
7.30 -
7.31 -<p>There are two principal methods of introducing authentication and applying
7.32 +<p>There are two principal methods of introducing authentication and
7.33 +applying
7.34 access control to WebStack applications:</p>
7.35 <ul>
7.36 <li><a href="authenticators.html">Application-Wide Authenticators</a></li>
7.37 <li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li>
7.38 </ul>
7.39 -
7.40 <p>Here is a comparison of the features of these mechanisms:</p>
7.41 -
7.42 -<table border="1" cellspacing="0" cellpadding="5">
7.43 +<table border="1" cellpadding="5" cellspacing="0">
7.44 <tbody>
7.45 <tr>
7.46 <td></td>
7.47 @@ -35,22 +31,41 @@
7.48 </tr>
7.49 <tr>
7.50 <th>Deployment</th>
7.51 - <td>Some Web server configuration required.<br />
7.52 - Application only requires an additional object for
7.53 - authentication.</td>
7.54 - <td>An additional login application or resource must be deployed.</td>
7.55 + <td>
7.56 + <ul>
7.57 + <li>Some Web server configuration required.</li>
7.58 + <li>The application only requires an additional object to be
7.59 +instantiated to support authentication.</li>
7.60 + </ul>
7.61 + </td>
7.62 + <td>
7.63 + <ul>
7.64 + <li>An additional login application or resource must be
7.65 +deployed.</li>
7.66 + </ul>
7.67 + </td>
7.68 </tr>
7.69 <tr>
7.70 <th>Flexibility</th>
7.71 - <td>Possibly inflexible user experience - users may only get the login
7.72 - dialogue; probably no logout function.<br />
7.73 - HTTP-style authentication is well understood and supported when
7.74 - automating client access.</td>
7.75 - <td>The login and logout activities can be customised to suit the
7.76 - appearance of the rest of the application.<br />
7.77 - Many applications can share the same login application, providing a
7.78 - "single sign-on" experience and potentially reduced administrative
7.79 - overhead.</td>
7.80 + <td>
7.81 + <ul>
7.82 + <li>The user experience may seem too inflexible or unfriendly -
7.83 +users may only get the login dialogue.</li>
7.84 + <li>There is also probably no logout function, since it
7.85 +requires browser support.</li>
7.86 + <li> HTTP-style authentication is well understood and supported
7.87 +when automating client access.</li>
7.88 + </ul>
7.89 + </td>
7.90 + <td>
7.91 + <ul>
7.92 + <li>The login and logout activities can be customised to suit
7.93 +the appearance of the rest of the application.</li>
7.94 + <li> Many applications can share the same login application,
7.95 +providing a "single sign-on" experience and potentially reduced
7.96 +administrative overhead.</li>
7.97 + </ul>
7.98 + </td>
7.99 </tr>
7.100 </tbody>
7.101 </table>
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/docs/sessions-servers.html Sat Apr 30 20:31:51 2005 +0000
8.3 @@ -0,0 +1,64 @@
8.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
8.5 +<html xmlns="http://www.w3.org/1999/xhtml">
8.6 +<head>
8.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
8.8 + <title>Server Environment Support for Sessions</title>
8.9 + <meta name="generator"
8.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
8.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
8.12 +</head>
8.13 +<body>
8.14 +<h1>Server Environment Support for Sessions</h1>
8.15 +<p>Various server environments or frameworks do not support sessions
8.16 +directly. In order to provide primitive support for sessions within
8.17 +WebStack upon such frameworks, the <code>WebStack.Helpers.Session</code>
8.18 +module is used to provide a simple file-based session store. Before
8.19 +deploying an application on one of these frameworks, it is necessary to
8.20 +create a directory called <code>WebStack-sessions</code> in a
8.21 +particular location so that the storage of session information will
8.22 +work.</p>
8.23 +<p>The location of the <code>WebStack-sessions</code> directory
8.24 +depends on the framework as summarised below:</p>
8.25 +<table style="text-align: left; width: 80%;" align="center" border="1"
8.26 + cellpadding="5" cellspacing="0" width="80%">
8.27 + <tbody>
8.28 + <tr>
8.29 + <th style="text-align: center;">Server Environment</th>
8.30 + <th style="text-align: center;">Directory Location</th>
8.31 + </tr>
8.32 + <tr>
8.33 + <td align="undefined" valign="undefined">BaseHTTPRequestHandler</td>
8.34 + <td align="undefined" valign="undefined">The directory where the
8.35 +server is run.</td>
8.36 + </tr>
8.37 + <tr>
8.38 + <td align="undefined" valign="undefined">CGI</td>
8.39 + <td align="undefined" valign="undefined">The directory where the
8.40 +handler resides.</td>
8.41 + </tr>
8.42 + <tr>
8.43 + <td align="undefined" valign="undefined">mod_python</td>
8.44 + <td align="undefined" valign="undefined">The server root (such
8.45 +as <code>/usr/local/apache2</code>).</td>
8.46 + </tr>
8.47 + <tr>
8.48 + <td align="undefined" valign="undefined">Twisted</td>
8.49 + <td align="undefined" valign="undefined">The directory where the
8.50 +server is run.</td>
8.51 + </tr>
8.52 + </tbody>
8.53 +</table>
8.54 +<p>Note that the <code>WebStack-sessions</code> directory must
8.55 +have the appropriate ownership and privileges necessary for the server
8.56 +or framework to write session information into it.<br />
8.57 +</p>
8.58 +<h2>Unsupported Environments and Framework Issues</h2>
8.59 +<ul>
8.60 + <li>Webware 0.8.1 has problems creating sessions and is therefore not
8.61 +supported.</li>
8.62 + <li>Webware releases later than 0.8.1 (at least until the 2004-02-06
8.63 +CVS snapshot used for testing) do not support session detection or
8.64 +expiry correctly.</li>
8.65 +</ul>
8.66 +</body>
8.67 +</html>
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/docs/sessions-usage.html Sat Apr 30 20:31:51 2005 +0000
9.3 @@ -0,0 +1,70 @@
9.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
9.5 +<html xmlns="http://www.w3.org/1999/xhtml">
9.6 +<head>
9.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
9.8 + <title>Using Sessions</title>
9.9 + <meta name="generator"
9.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
9.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
9.12 +</head>
9.13 +<body>
9.14 +<h1>Using Sessions</h1>
9.15 +<p>Unlike cookies, session information is always stored on the server
9.16 +and is not communicated back to the user. Consequently, sessions have
9.17 +several advantages over cookies, and the uses of sessions may include
9.18 +the storage of...</p>
9.19 +<ul>
9.20 + <li>Sensitive or private information. Although such information can
9.21 +be stored without needing to
9.22 +encrypt it, in many applications you will still want to
9.23 +encrypt such information anyway, no matter where it is stored or how it
9.24 +is communicated.</li>
9.25 + <li>Large amounts of session information can be stored, or at least
9.26 +larger amounts than are typically allowed using cookies.</li>
9.27 +</ul>
9.28 +<div class="WebStack">
9.29 +<h3>WebStack API - Using Sessions</h3>
9.30 +<p>In WebStack, a session appears as a dictionary to applications and
9.31 +is acquired for a specific user through the <a
9.32 + href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>
9.33 +object. The following methods are provided in the transaction for
9.34 +accessing and maintenance of session information:</p>
9.35 +<dl>
9.36 + <dt><code>get_session</code></dt>
9.37 + <dd>This method returns the session for the identified user. The <code>create</code>
9.38 +parameter can be set to a true value to create a new session for a user
9.39 +if no session previously existed; otherwise <code>None</code> is
9.40 +returned in such situations.</dd>
9.41 + <dt><code>expire_session</code></dt>
9.42 + <dd>This method causes the session information associated with the
9.43 +identified user to be forgotten. Note that this may not really happen
9.44 +until the user sends another request, and that the <code>get_session</code>
9.45 +method may still return the current session.</dd>
9.46 +</dl>
9.47 +<p>Session objects, which resemble dictionaries, employ plain Python
9.48 +strings as keys in the accessing of information, and as the values
9.49 +loaded and stored inside the session. Unlike cookies, upon setting
9.50 +information within a session, such information is remembered thereafter
9.51 +without any other actions being necessary to make that information
9.52 +permanent or persistent.</p>
9.53 +<dl>
9.54 +</dl>
9.55 +</div>
9.56 +<h2>How and When to Access Sessions</h2>
9.57 +<p>To find out if a session has already been created, ask for a session
9.58 +by specifying that one should not be automatically created:</p>
9.59 +<pre> # In the respond method...<br /> session = trans.get_session(create=0) # session is None if no session already exists</pre>
9.60 +<p>To ensure that a session exists, just ask for a session:</p>
9.61 +<pre> # In the respond method...<br /> session = trans.get_session() # this is the same as using create=1</pre>
9.62 +<p>Session contents may mostly be accessed like dictionaries, so to
9.63 +access the keys within a session the following code could be used:</p>
9.64 +<pre> # In the respond method after obtaining a session...<br /> for key in session.keys():<br /> [Do something with the key - perhaps obtain values.]</pre>
9.65 +<p>To test the presence of a key, and to access values associated with
9.66 +a key, the usual dictionary methods apply:</p>
9.67 +<pre> # In the respond method after obtaining the session...<br /> if session.has_key("my_data"):<br /> my_data = session["my_data"]<br /> [Do something with my_data.]<br /> session["my_data"] = my_data</pre>
9.68 +<p>The session for the user may be removed or "expired" as follows:</p>
9.69 +<pre> # In the respond method...<br /> trans.expire_session()</pre>
9.70 +<p>Note that WebStack automatically knows which session is to be
9.71 +expired since only one such session can exist for the identified user.</p>
9.72 +</body>
9.73 +</html>
10.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2 +++ b/docs/sessions.html Sat Apr 30 20:31:51 2005 +0000
10.3 @@ -0,0 +1,67 @@
10.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
10.5 +<html xmlns="http://www.w3.org/1999/xhtml">
10.6 +<head>
10.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
10.8 + <title>Sessions and Persistent Information</title>
10.9 + <meta name="generator"
10.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
10.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
10.12 +</head>
10.13 +<body>
10.14 +<h1>Sessions and Persistent Information</h1>
10.15 +<p>The term "session" is a technical term describing information which
10.16 +is remembered by an application for a particular user. Sessions work in
10.17 +conjunction which other mechanisms - typically <a href="cookies.html">cookies</a>
10.18 +and <a href="users.html">user identifiers</a> - like this:</p>
10.19 +<ol>
10.20 + <li> The application finds out who the user is - this information may
10.21 +be recorded in a <a href="cookies.html">cookie</a> or be associated
10.22 +with a request in <a href="users.html">some other way</a>.</li>
10.23 + <li>It then accesses a data store containing information associated
10.24 +different users.</li>
10.25 + <li>Finally, it accesses information specific to the stated user -
10.26 +this is that particular user's session.</li>
10.27 +</ol>
10.28 +<h2>Sessions vs. Persistent Information</h2>
10.29 +<p>Information can be said to be "persistent" when it is
10.30 +remembered beyond the lifetime of a particular request to an
10.31 +application. Sessions, meanwhile, are effectively a special case of
10.32 +persistent information - data is addressed or accessed using each
10.33 +user's identity, and the information is partitioned in such a way that
10.34 +sessions cannot be shared between users.</p>
10.35 +<table style="text-align: left; width: 80%;" align="center" border="1"
10.36 + cellpadding="5" cellspacing="0" width="80%">
10.37 + <tbody>
10.38 + <tr>
10.39 + <td></td>
10.40 + <th style="text-align: center;">Sessions</th>
10.41 + <th style="text-align: center;">Persistent Information</th>
10.42 + </tr>
10.43 + <tr>
10.44 + <th>Access</th>
10.45 + <td align="undefined" valign="undefined">Through user identity.</td>
10.46 + <td align="undefined" valign="undefined">Through any relevant
10.47 +concept: users, documents, orders, products, locations - anything an
10.48 +application might want to remember.</td>
10.49 + </tr>
10.50 + <tr>
10.51 + <th>Partitioning</th>
10.52 + <td align="undefined" valign="undefined">By user identity. Each
10.53 +user has its own private data store.</td>
10.54 + <td align="undefined" valign="undefined">Arbitrary. Many data
10.55 +stores or data sources may be set up. The data may be shared across the
10.56 +entire application or there may be access controls in place.</td>
10.57 + </tr>
10.58 + </tbody>
10.59 +</table>
10.60 +<p>Access to persistent information in general can be done by using
10.61 +database access libraries, for example - see <a href="integrating.html">"Integrating
10.62 +with Other Systems"</a> for more details. </p>
10.63 +<h2>More About Sessions</h2>
10.64 +<ul>
10.65 + <li><a href="sessions-usage.html">Using Sessions</a></li>
10.66 + <li><a href="sessions-servers.html">Server Environment Support for
10.67 +Sessions</a></li>
10.68 +</ul>
10.69 +</body>
10.70 +</html>
11.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2 +++ b/docs/users.html Sat Apr 30 20:31:51 2005 +0000
11.3 @@ -0,0 +1,43 @@
11.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
11.5 +<html xmlns="http://www.w3.org/1999/xhtml">
11.6 +<head>
11.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
11.8 + <title>Users and Authentication</title>
11.9 + <meta name="generator"
11.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
11.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
11.12 +</head>
11.13 +<body>
11.14 +<h1>Users and Authentication</h1>
11.15 +<p>One way of discovering the identity of the user sending a request
11.16 +into your application is to test the identity using methods on the
11.17 +transaction object. Before this can be made to work, you must set
11.18 +up authentication for your application, as described in <a
11.19 + href="securing.html">"Securing a WebStack Application"</a>. Once
11.20 +authentication is working, every request that arrives in the
11.21 +application will have the identity of the user attached automatically.</p>
11.22 +<h2>Uses of User Identity</h2>
11.23 +<p>Having access to a user's identity can be useful in making decisions
11.24 +about which operations that user is able to perform within your
11.25 +application. Moreover, the user identity provided by authentication
11.26 +mechanisms can tell you more about who that user is, as opposed to
11.27 +typical session information which, on its own, can only really confirm
11.28 +that the user in question has visited the application before.</p>
11.29 +<div class="WebStack">
11.30 +<h3>WebStack API - User Identity</h3>
11.31 +<p>Transaction objects have the following methods for inspecting and
11.32 +redefining the identity of users:</p>
11.33 +<dl>
11.34 + <dt><code>get_user</code></dt>
11.35 + <dd>This gets the name of the user attempting to access the
11.36 +application.</dd>
11.37 + <dt><code>set_user</code></dt>
11.38 + <dd>This sets the name of the user, thus affecting subsequent calls
11.39 +to <code>get_user</code>, allowing certain parts of an application to
11.40 +view users according to other criteria than their basic username - for
11.41 +example, one might use <code>set_user</code> to redefine each user's
11.42 +identity in terms of the role that user may have in an application.</dd>
11.43 +</dl>
11.44 +</div>
11.45 +</body>
11.46 +</html>