1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/authenticators.html Sat Apr 09 23:25:58 2005 +0000
1.3 @@ -0,0 +1,101 @@
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>Application-Wide Authenticators</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>Application-Wide Authenticators</h1>
1.16 +
1.17 +<p>Authenticators are special classes which can, in conjunction with
1.18 +mechanisms in the server environment, judge whether a user of an application
1.19 +is recognised or not. The process of using authenticators is as follows:</p>
1.20 +<ol>
1.21 + <li>Set up authentication in the server environment or framework in which
1.22 + the application is to be deployed.</li>
1.23 + <li>Introduce an authenticator class in the application.</li>
1.24 +</ol>
1.25 +
1.26 +<h2>Setting Up Authentication</h2>
1.27 +
1.28 +<p>The exact details of configuring authentication mechanisms in each server
1.29 +environment may vary substantially. For example, Apache environments require
1.30 +that <code>Auth</code> directives be specified in the Apache configuration
1.31 +files (see <code>docs/ModPython/NOTES.txt</code>); in Zope environments,
1.32 +protected folders can be defined to hold the application when deployed (see
1.33 +<code>docs/Zope/NOTES.txt</code>).</p>
1.34 +
1.35 +<h2>Defining an Authenticator</h2>
1.36 +
1.37 +<p>An authenticator must be defined within your application in order to make
1.38 +decisions about users who have presented their credentials; this
1.39 +authenticator will respond with a decision when prompted by the server or
1.40 +underlying framework, either allowing or denying access for the user whose
1.41 +identity has been presented to the server/framework.</p>
1.42 +
1.43 +<p>The code for an authenticator usually looks like this:</p>
1.44 +<pre>class MyAuthenticator:
1.45 +
1.46 + "This is an authenticator - something which decides whether a user is known to the application."
1.47 +
1.48 + def authenticate(self, trans):
1.49 + user = trans.get_user()
1.50 + [Make a decision about the validity of the user.]
1.51 + [Return a true value if the user is allowed to access the application.]
1.52 + [Return a false value if the user is not recognised or allowed to access the application.]
1.53 +
1.54 + def get_auth_type(self):
1.55 + "This method returns 'Basic' in most deployments."
1.56 + return "Basic"
1.57 +
1.58 + def get_realm(self):
1.59 + "This method returns something to distinguish this authentication mechanism from others."
1.60 + return "MyRealm"</pre>
1.61 +
1.62 +<p>In this mechanism, authenticators rely on authentication information from
1.63 +the server/framework and have a "global" effect on access to the application.
1.64 +However, it is always possible to test the user identity later on and to
1.65 +change the way an application behaves accordingly.</p>
1.66 +
1.67 +<div class="WebStack">
1.68 +<h3>WebStack API - User Identity</h3>
1.69 +
1.70 +<p>Transaction objects have the following methods for inspecting and
1.71 +redefining the identity of users:</p>
1.72 +<dl>
1.73 + <dt><code>get_user</code></dt>
1.74 + <dd>This gets the name of the user attempting to access the
1.75 + application.</dd>
1.76 + <dt><code>set_user</code></dt>
1.77 + <dd>This sets the name of the user, thus affecting subsequent calls to
1.78 + <code>get_user</code>, allowing certain parts of an application to view
1.79 + users according to other criteria than their basic username - for
1.80 + example, one might use <code>set_user</code> to redefine each user's
1.81 + identity in terms of the role that user may have in an application.</dd>
1.82 +</dl>
1.83 +</div>
1.84 +
1.85 +<h2>Introducing an Authenticator</h2>
1.86 +
1.87 +<p>Authenticator objects are created in the adapter code - see <a
1.88 +href="writing-adapters.html">"Writing Adapters"</a> for more information.</p>
1.89 +
1.90 +<h2>Anonymous Access</h2>
1.91 +
1.92 +<p>With application-wide authenticators, anonymous access to resources and
1.93 +applications can be difficult to permit alongside access by specific users,
1.94 +mostly because servers and frameworks which employ HTTP authentication
1.95 +schemes do so globally for a given application.</p>
1.96 +
1.97 +<h2>Logout Functions</h2>
1.98 +
1.99 +<p>With application-wide authenticators, a logout function may not be
1.100 +available if the server/framework has been configured to use HTTP
1.101 +authentication schemes, mainly because no logout mechanism generally exists
1.102 +for such schemes.</p>
1.103 +</body>
1.104 +</html>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/login-redirect.html Sat Apr 09 23:25:58 2005 +0000
2.3 @@ -0,0 +1,220 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml">
2.8 +<head>
2.9 + <title>LoginRedirect and Login Modules</title>
2.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.12 +</head>
2.13 +
2.14 +<body>
2.15 +<h1>LoginRedirect and Login Modules</h1>
2.16 +
2.17 +<p>The <code>LoginRedirect</code> and <code>Login</code> modules provide a
2.18 +"single sign-on" environment for WebStack applications. Unlike the
2.19 +authenticator-only approach, each application or part of an application
2.20 +utilising this mechanism must be wrapped inside a
2.21 +<code>LoginRedirectResource</code> object which determines whether a given
2.22 +transaction contains information identifying the application's user.</p>
2.23 +
2.24 +<h2>How the Modules Work</h2>
2.25 +
2.26 +<p>When a request arrives in the application, the following things happen:</p>
2.27 +<ol>
2.28 + <li>The <code>LoginRedirectResource</code> examines the transaction and
2.29 + attempts to find out whether it identifies a user.</li>
2.30 + <li>Should sufficient information be present in the transaction, the user
2.31 + is allowed to access the application and is identified in the normal way
2.32 + (ie. the <code>get_user</code> method on the transaction object).</li>
2.33 + <li>Otherwise, a redirect occurs to a login screen provided by a
2.34 + <code>LoginResource</code> object which then presents a login form to be
2.35 + completed by the user.</li>
2.36 + <li>The <code>LoginResource</code> object then receives the completed form
2.37 + information and verifies the identity of the user, testing the supplied
2.38 + credentials against the credentials database specified in the deployment
2.39 + of the resource.</li>
2.40 + <li>Upon successful authentication, the user is redirected back to the
2.41 + application, guarded by <code>LoginRedirectResource</code> which should
2.42 + let the user gain access.</li>
2.43 +</ol>
2.44 +
2.45 +<h2>Introducing LoginRedirectResource</h2>
2.46 +
2.47 +<p>The easiest way of introducing <code>LoginRedirectResource</code> objects
2.48 +is to do so in the adapter code, as described in <a
2.49 +href="writing-adapters.html">"Writing Adapters"</a>. The most significant
2.50 +difference between deploying normal resources and
2.51 +<code>LoginRedirectResource</code> objects is the special way in which such
2.52 +objects are initialised and that they themselves contain the actual resources
2.53 +of the application which provide the real functionality.</p>
2.54 +
2.55 +<p>Here is what the deployment of <code>LoginRedirectResource</code> objects
2.56 +often looks like:</p>
2.57 +<pre>from WebStack.Resources.LoginRedirect import LoginRedirectResource, LoginRedirectAuthenticator
2.58 +
2.59 +deploy(
2.60 + LoginRedirectResource(
2.61 + login_url="http://localhost:8081",
2.62 + app_url="http://localhost:8080",
2.63 + resource=[some resource object which provides the real application behaviour],
2.64 + authenticator=LoginRedirectAuthenticator(secret_key="horses"),
2.65 + anonymous_parameter_name="anonymous",
2.66 + logout_parameter_name="logout"
2.67 + )
2.68 +)</pre>
2.69 +
2.70 +<p>Certain parts of the resource are configurable, according to which other
2.71 +services may exist in or alongside the deployed application.</p>
2.72 +
2.73 +<div class="WebStack">
2.74 +<h3>WebStack API - LoginRedirectResource Initialisation</h3>
2.75 +
2.76 +<p>The following parameters must be provided when initialising a
2.77 +<code>LoginRedirectResource</code> object:</p>
2.78 +<dl>
2.79 + <dt><code>login_url</code></dt>
2.80 + <dd>This specifies the location of the separate login application or
2.81 + resource which presents a login screen to unidentified users and logs
2.82 + them in.</dd>
2.83 + <dt><code>app_url</code></dt>
2.84 + <dd>This specifies the location of the application itself - it must
2.85 + therefore be updated according to where the application is eventually
2.86 + deployed.</dd>
2.87 + <dt><code>resource</code></dt>
2.88 + <dd>This provides the resource object which contains the application
2.89 + code, or at least the entry point into various parts of the application
2.90 + code.</dd>
2.91 + <dt><code>authenticator</code></dt>
2.92 + <dd>This provides the authenticator object which decides whether a user
2.93 + is recognised or not. The special
2.94 + <code>LoginRedirectAuthenticator</code> is recommended and must itself
2.95 + be configured using a <code>secret_key</code> parameter which is used
2.96 + to protect user-related information exchanged over the network - the
2.97 + value provided for <code>secret_key</code> must be unguessable and kept
2.98 + secret from unauthorised individuals.</dd>
2.99 + <dt><code>anonymous_parameter_name</code></dt>
2.100 + <dd>An optional parameter providing the name of a request parameter (see
2.101 + <a href="parameters.html">"Request Parameters and Uploads"</a>) which,
2.102 + if specified, permits a user to access an application without being
2.103 + formally identified. If omitted, all users will be required to identify
2.104 + themselves explicitly.</dd>
2.105 + <dt><code>anonymous_username</code></dt>
2.106 + <dd>An optional parameter providing the name given to anonymous users
2.107 + which is returned when a transaction's <code>get_user</code> method is
2.108 + called. By default, <code>anonymous</code> is used for such users.</dd>
2.109 + <dt><code>logout_parameter_name</code></dt>
2.110 + <dd>An optional parameter providing the name of a request parameter
2.111 + which, if specified, permits a user to log out of an application. If
2.112 + omitted, no means of logging out will be available, although deleting
2.113 + browser cookies will probably have the desired effect.</dd>
2.114 + <dt><code>logout_url</code></dt>
2.115 + <dd>An optional parameter which indicates the location of the resource
2.116 + visited when a user logs out. By default, the location is a path to the
2.117 + root resource in the server environment of the application.</dd>
2.118 + <dt><code>use_logout_redirect</code></dt>
2.119 + <dd>An optional parameter which determines whether users logging out of
2.120 + an application will be redirected to the <code>logout_url</code> or
2.121 + not. By default, users are redirected, but if a false value is given
2.122 + for this parameter, a simple page is presented to the user informing
2.123 + them of the situation - it is recommended that a subclass of
2.124 + <code>LoginRedirectResource</code> be employed should more informative
2.125 + pages be required.</dd>
2.126 +</dl>
2.127 +</div>
2.128 +
2.129 +<h3>Redirection From/To the Application</h3>
2.130 +
2.131 +<p>Some server/framework environments do not permit automatic redirection
2.132 +back to the application, notably Apache/mod_python. In such cases, a success
2.133 +screen is presented to the user with a link to the application they were
2.134 +attempting to access.</p>
2.135 +
2.136 +<h3>The Role of Authenticators</h3>
2.137 +
2.138 +<p>In this mechanism, authenticators are employed, but only to verify the
2.139 +credentials of users when <code>LoginResource</code> or
2.140 +<code>LoginRedirectResource</code> objects are accessed. Although it should
2.141 +be possible to reuse <a href="authenticators.html">application-wide
2.142 +authenticator</a> classes in conjunction with <code>LoginResource</code>,
2.143 +such classes will not provide the additional functionality required to
2.144 +support the "single sign-on" aspects of this mechanism - mixing in such
2.145 +classes with <code>LoginAuthenticator</code> may provide a solution to this
2.146 +issue, however.</p>
2.147 +
2.148 +<h2>Deploying a Login Application</h2>
2.149 +
2.150 +<p>In order for this authentication mechanism to function in its entirety, a
2.151 +login application (or resource) must be available to authenticate
2.152 +unidentified users. It may already be the case that such an application has
2.153 +been deployed and is available at a certain URL - if so, it should be
2.154 +sufficient for a <code>LoginRedirectResource</code> object to be configured
2.155 +as described above, making sure that the <code>login_url</code> actually
2.156 +refers to the location of the existing login application, and that the
2.157 +<code>authenticator</code> object's <code>secret_key</code> is consistent
2.158 +with the way the existing login application has been set up.</p>
2.159 +
2.160 +<p>However, if no existing login application (or resource) exists, one may be
2.161 +deployed using adapter code similar to the following:</p>
2.162 +<pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy
2.163 +from WebStack.Resources.Login import LoginResource, LoginAuthenticator
2.164 +
2.165 +deploy(
2.166 + LoginResource( # This is the login application's main resource.
2.167 + LoginAuthenticator( # This provides authentication support.
2.168 + secret_key="horses",
2.169 + credentials=(
2.170 + ("badger", "abc"),
2.171 + ("vole", "xyz"),
2.172 + )
2.173 + )
2.174 + ),
2.175 + address=("", 8081)
2.176 +)</pre>
2.177 +
2.178 +<p>The above code merely starts a login application in the
2.179 +BaseHTTPRequestHandler environment at a specific address (which corresponds
2.180 +to that specified in the <code>login_url</code> of the
2.181 +<code>LoginRedirectResource</code> used above) and provides a
2.182 +<code>LoginAuthenticator</code> object configured to use a
2.183 +<code>secret_key</code> (which corresponds to the <code>secret_key</code>
2.184 +used in the <code>authenticator</code> of the
2.185 +<code>LoginRedirectResource</code> above) and some user credentials. The user
2.186 +credentials define which users are to be recognised for applications which
2.187 +employ this login application, along with the password details of each
2.188 +user.</p>
2.189 +
2.190 +<div class="WebStack">
2.191 +<h3>WebStack API - LoginAuthenticator Credentials</h3>
2.192 +
2.193 +<p>When initialising a <code>LoginAuthenticator</code> object with
2.194 +credentials, the supplied credentials object must support tests on its
2.195 +contents of the following form:</p>
2.196 +<pre>(username, password) in credentials</pre>
2.197 +
2.198 +<p>In other words, the credentials object must either be a sequence of
2.199 +username and password tuples, or it must implement the
2.200 +<code>__contains__</code> method and accept such tuples as arguments to that
2.201 +method.</p>
2.202 +</div>
2.203 +
2.204 +<h2>Anonymous Access</h2>
2.205 +
2.206 +<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
2.207 +possible to declare a particular request parameter (see
2.208 +<code>anonymous_parameter_name</code> above) which must be present in the URL
2.209 +used to access a particular application for the client to be given anonymous
2.210 +access. Consequently, anonymous users are then identified specially with a
2.211 +special username that can also be configured (see
2.212 +<code>anonymous_username</code> above).</p>
2.213 +
2.214 +<h2>Logout Functions</h2>
2.215 +
2.216 +<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
2.217 +possible to declare a particular request parameter (see
2.218 +<code>logout_parameter_name</code> above) which must be present in the URL
2.219 +used to access a particular application for the client to be logged out. A
2.220 +special logout confirmation URL may also be configured (see
2.221 +<code>logout_url</code> and <code>use_logout_redirect</code> above).</p>
2.222 +</body>
2.223 +</html>
3.1 --- a/docs/securing.html Sat Apr 09 23:25:43 2005 +0000
3.2 +++ b/docs/securing.html Sat Apr 09 23:25:58 2005 +0000
3.3 @@ -1,6 +1,6 @@
3.4 <?xml version="1.0" encoding="iso-8859-1"?>
3.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.7 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.8 <html xmlns="http://www.w3.org/1999/xhtml">
3.9 <head>
3.10 <title>Securing a WebStack Application</title>
3.11 @@ -26,76 +26,10 @@
3.12 <code>WebStack.Resources.Login</code> modules.</li>
3.13 </ul>
3.14
3.15 -<h3>Application-Wide Authenticators</h3>
3.16 -
3.17 -<p>First, set up the usage of such authentication mechanisms in the
3.18 -server/framework environment. For example, introduce <code>Auth</code>
3.19 -directives in your Apache configuration (see
3.20 -<code>docs/ModPython/NOTES.txt</code>) or protected folders in your Zope
3.21 -instance (see <code>docs/Zope/NOTES.txt</code>).</p>
3.22 -
3.23 -<p>Then, define an authenticator when deploying your application; this
3.24 -authenticator will respond with a decision when prompted by the server or
3.25 -underlying framework, either allowing or denying access for the user whose
3.26 -identity has been presented to the server/framework.</p>
3.27 -
3.28 -<p>In this mechanism, authenticators rely on authentication information from
3.29 -the server/framework and have a "global" effect on access to the
3.30 -application.</p>
3.31 -
3.32 -<h3>LoginRedirect and Login Modules</h3>
3.33 -
3.34 -<p>The <code>LoginRedirect</code> and <code>Login</code> modules provide a
3.35 -"single sign-on" environment for WebStack applications. Unlike the
3.36 -authenticator-only approach, each application or part of an application
3.37 -utilising this mechanism must be wrapped inside a
3.38 -<code>LoginRedirectResource</code> object which determines whether a given
3.39 -transaction contains information identifying the application's user.</p>
3.40 -
3.41 -<p>Should sufficient information be present in the transaction, the user is
3.42 -allowed to access the application and is identified in the normal way (ie.
3.43 -the <code>get_user</code> method on the transaction object). Otherwise, a
3.44 -redirect occurs to a login screen provided by a <code>LoginResource</code>
3.45 -object which then presents a login form to be completed by the user.</p>
3.46 -
3.47 -<p>The <code>LoginResource</code> object verifies the identity of the user,
3.48 -testing the supplied credentials against the credentials database specified
3.49 -in the deployment of the resource. Upon successful authentication, the user
3.50 -is redirected back to the application, which should let the user gain
3.51 -access.</p>
3.52 -
3.53 -<p>Some server/framework environments do not permit automatic redirection
3.54 -back to the application, notably Apache/mod_python. In such cases, a success
3.55 -screen is presented to the user with a link to the application they were
3.56 -attempting to access.</p>
3.57 -
3.58 -<p>In this mechanism, authenticators are employed, but only to verify the
3.59 -credentials of users when <code>LoginResource</code> or
3.60 -<code>LoginRedirectResource</code> objects are accessed.</p>
3.61 -
3.62 -<h3>Anonymous Access</h3>
3.63 -
3.64 -<p>With application-wide authenticators, anonymous access to resources and
3.65 -applications can be difficult to permit alongside access by specific users,
3.66 -mostly because servers and frameworks which employ HTTP authentication
3.67 -schemes do so globally for a given application.</p>
3.68 -
3.69 -<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
3.70 -possible to declare a particular request parameter which must be present in
3.71 -the URL used to access a particular application for the client to be given
3.72 -anonymous access. Consequently, anonymous users are then identified specially
3.73 -with a special username that can also be configured.</p>
3.74 -
3.75 -<h3>Logout Functions</h3>
3.76 -
3.77 -<p>With application-wide authenticators, a logout function may not be
3.78 -available if the server/framework has been configured to use HTTP
3.79 -authentication schemes, since no such function is defined for such
3.80 -schemes.</p>
3.81 -
3.82 -<p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is
3.83 -possible to declare a particular request parameter which must be present in
3.84 -the URL used to access a particular application for the client to be logged
3.85 -out. A special logout confirmation URL may also be configured.</p>
3.86 +<h2>Choosing an Authentication Strategy</h2>
3.87 +<ul>
3.88 + <li><a href="authenticators.html">Application-Wide Authenticators</a></li>
3.89 + <li><a href="login-redirect.html">LoginRedirect and Login Modules</a></li>
3.90 +</ul>
3.91 </body>
3.92 </html>