2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/openid-login-redirect.html Thu May 01 21:44:39 2008 +0000
2.3 @@ -0,0 +1,236 @@
2.4 +<?xml version="1.0" encoding="iso-8859-1"?>
2.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.6 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
2.7 + <title>OpenID Modules for Initiation, Login and Redirection</title>
2.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.9 +<body>
2.10 +<h1>OpenID Modules for Initiation, Login and Redirection</h1>
2.11 +
2.12 +<p>A number of modules are provided to support the
2.13 +<a href="http://openid.net/">OpenID</a> identity standards, and these serve
2.14 +the following purposes:</p>
2.15 +
2.16 +<dl>
2.17 +<dt><code>OpenIDInitiation</code></dt>
2.18 +<dd>Requests and handles the identity of the user, redirecting them to their
2.19 +OpenID (identity) provider.</dd>
2.20 +<dt><code>OpenIDLogin</code></dt>
2.21 +<dd>Provides basic OpenID provider functionality, allowing users to
2.22 +authenticate themselves and to be redirected back to the application which
2.23 +demanded their authentication.</dd>
2.24 +<dt><code>OpenIDRedirect</code></dt>
2.25 +<dd>Provides checking of user identity with redirection to the initiation page
2.26 +for unauthenticated users.</dd>
2.27 +</dl>
2.28 +
2.29 +<p>A combination of the functionality in <code>OpenIDInitiation</code> and
2.30 +<code>OpenIDRedirect</code> should be sufficient for applications to accept
2.31 +visitors with OpenID identities. With all of the above modules in use, an
2.32 +application could be self-sufficient in a similar way to that enjoyed through
2.33 +the use of the normal <a href="login-redirect.html">LoginRedirect and Login
2.34 +Modules</a>.</p>
2.35 +
2.36 +<h2>How the Modules Work</h2>
2.37 +
2.38 +<p>Similar in many ways to the functioning of the <a
2.39 +href="login-redirect.html">LoginRedirect and Login Modules</a>, when a request
2.40 +arrives in the application, the following things happen:</p>
2.41 +
2.42 +<ol>
2.43 + <li>The <code>OpenIDRedirectResource</code> examines the transaction
2.44 +and attempts to find out whether it identifies a user.</li>
2.45 + <li>Should sufficient information be present in the transaction, the
2.46 +user is allowed to access the application and is identified in the
2.47 +normal way (ie. the <code>get_user</code> method on the transaction
2.48 +object).</li>
2.49 + <li>Otherwise, a redirect occurs to an initiation screen provided by an
2.50 +<code>OpenIDInitiationResource</code> which requests the users's OpenID
2.51 +identifier.</li>
2.52 + <li>The <code>OpenIDInitiationResource</code> object receives any identity
2.53 +information and causes a redirect to the user's OpenID provider.</li>
2.54 + <li>Where the OpenID provider is hosted by the application infrastructure,
2.55 +the user is actually redirected to a login screen provided by an
2.56 +<code>OpenIDLoginResource</code> object which then presents a login form to be
2.57 +completed by the user (similar to that provided by the
2.58 +<code>LoginResource</code> class).</li>
2.59 + <li>The <code>OpenIDLoginResource</code> object then receives the
2.60 +completed form information and verifies the identity of the user,
2.61 +testing the supplied credentials against the credentials database
2.62 +specified in the deployment of the resource.</li>
2.63 + <li>Upon successful authentication, the user is redirected back to
2.64 +the application, guarded by <code>OpenIDRedirectResource</code> which
2.65 +should let the user gain access.</li>
2.66 +</ol>
2.67 +
2.68 +<h2>Introducing OpenIDRedirectResource</h2>
2.69 +
2.70 +<p>Like <code>LoginRedirectResource</code>, introducing
2.71 +<code>OpenIDRedirectResource</code> into an application can be done in the
2.72 +adapter code, as described in <a href="writing-adapters.html">"Writing
2.73 +Adapters"</a>. The most significant difference between deploying normal
2.74 +resources and <code>LoginRedirectResource</code> objects is the special way in
2.75 +which such objects are initialised and that they themselves contain the actual
2.76 +resources of the application which provide the real functionality.</p>
2.77 +
2.78 +<p>Here is what the deployment of <code>OpenIDRedirectResource</code>
2.79 +objects often looks like:</p>
2.80 +
2.81 +<pre>
2.82 +from WebStack.Resources.OpenIDRedirect import OpenIDRedirectResource, OpenIDRedirectAuthenticator
2.83 +
2.84 +deploy(
2.85 + OpenIDRedirectResource(
2.86 + login_url="http://localhost:8080/login",
2.87 + app_url="http://localhost:8080",
2.88 + resource=[some resource object which provides the real application behaviour],
2.89 + authenticator=OpenIDRedirectAuthenticator(
2.90 + secret_key="horses",
2.91 + app_url="http://localhost:8080"
2.92 + ),
2.93 + anonymous_parameter_name="anonymous",
2.94 + logout_parameter_name="logout"
2.95 + )
2.96 + )
2.97 +</pre>
2.98 +
2.99 +<p>Here, the <code>OpenIDRedirectResource</code> uses the same terminology as
2.100 +the <code>LoginRedirectResource</code> and employs a <code>login_url</code>,
2.101 +but this actually refers to the URL where the initiation page will be
2.102 +displayed. In a sense, it is a kind of login page, but where the actual
2.103 +authentication will take place elsewhere.</p>
2.104 +
2.105 +<div class="WebStack">
2.106 +<h3>WebStack API - OpenIDRedirectResource Initialisation</h3>
2.107 +
2.108 +<p>The following parameters must be provided when initialising a
2.109 +<code>OpenIDRedirectResource</code> object:</p>
2.110 +
2.111 +<dl>
2.112 + <dt><code>login_url</code></dt>
2.113 + <dd>This specifies the location of the initiation resource which requests
2.114 +identity details from unidentified users.</dd>
2.115 + <dt><code>app_url</code></dt>
2.116 + <dd>This specifies the location of the application itself - it must
2.117 +therefore be updated according to where the application is eventually
2.118 +deployed. This should be the "bare" reference using a protocol, host and port,
2.119 +not including any path information.</dd>
2.120 + <dt><code>resource</code></dt>
2.121 + <dd>This provides the resource object which contains the application
2.122 +code, or at least the entry point into various parts of the application
2.123 +code.</dd>
2.124 + <dt><code>authenticator</code></dt>
2.125 + <dd>This provides the authenticator object which decides whether a
2.126 +user is recognised or not. The special <code>OpenIDRedirectAuthenticator</code>
2.127 +is recommended and must itself be configured using a <code>secret_key</code>
2.128 +parameter which is used to protect user-related information exchanged
2.129 +over the network - the value provided for <code>secret_key</code> must
2.130 +be unguessable and kept secret from unauthorised individuals. The
2.131 +<code>app_url</code> used to initialise the authenticator must be the same as
2.132 +the one provided to the <code>OpenIDRedirectResource</code>.</dd>
2.133 +</dl>
2.134 +
2.135 +<p>The following parameters are optional:</p>
2.136 +<dl>
2.137 + <dt><code>anonymous_parameter_name</code></dt>
2.138 + <dd>An optional parameter providing the name of a request parameter
2.139 +(see <a href="parameters.html">"Request Parameters and Uploads"</a>)
2.140 +which, if specified, permits a user to access an application without
2.141 +being formally identified. If omitted, all users will be required to
2.142 +identify themselves explicitly.</dd>
2.143 + <dt><code>anonymous_username</code></dt>
2.144 + <dd>An optional parameter providing the name given to anonymous users
2.145 +which is returned when a transaction's <code>get_user</code> method is
2.146 +called. By default, <code>anonymous</code> is used for such users.</dd>
2.147 + <dt><code>logout_parameter_name</code></dt>
2.148 + <dd>An optional parameter providing the name of a request parameter
2.149 +which, if specified, permits a user to log out of an application. If
2.150 +omitted, no means of logging out will be available, although deleting
2.151 +browser cookies will probably have the desired effect.</dd>
2.152 + <dt><code>logout_url</code></dt>
2.153 + <dd>An optional parameter which indicates the location of the
2.154 +resource visited when a user logs out. By default, the location is a
2.155 +path to the root resource in the server environment of the application.</dd>
2.156 + <dt><code>use_logout_redirect</code></dt>
2.157 + <dd>An optional parameter which determines whether users logging out
2.158 +of an application will be redirected to the <code>logout_url</code> or
2.159 +not. By default, users are redirected, but if a false value is given
2.160 +for this parameter, a simple page is presented to the user informing
2.161 +them of the situation - it is recommended that a subclass of <code>LoginRedirectResource</code>
2.162 +be employed should more informative pages be required.</dd><dt><code>path_encoding</code></dt><dd>An
2.163 +optional parameter indicating the character encoding used to generate
2.164 +(and, in other places, to interpret) URL-encoded character values in
2.165 +URLs and paths.</dd>
2.166 +</dl>
2.167 +
2.168 +<p>See the <a href="../apidocs/public/WebStack.Resources.LoginRedirect.LoginRedirectResource-class.html">API documentation</a> for the <code>LoginRedirectResource</code> class for more details.</p>
2.169 +</div>
2.170 +
2.171 +<h3>Further Notes</h3>
2.172 +
2.173 +<p>See <a href="login-redirect.html">LoginRedirect and Login Modules</a> for
2.174 +notes on redirection, application-wide authenticators, anonymous users and
2.175 +logout functionality.</p>
2.176 +
2.177 +<h2>Extending OpenIDRedirectResource</h2>
2.178 +
2.179 +<p>See <a href="login-redirect.html">LoginRedirect and Login Modules</a> for
2.180 +pertinent guidance on extending <code>LoginRedirectResource</code>, since such
2.181 +guidance also applies to <code>OpenIDRedirectResource</code>.</p>
2.182 +
2.183 +<h2>Deploying an OpenIDLogin Application</h2>
2.184 +
2.185 +<p>In order to provide OpenID login support for a self-sufficient application,
2.186 +a login application (or resource) must be available to authenticate unidentified
2.187 +users. It may already be the case that such an application has been deployed
2.188 +and is available at a certain URL - if so, it should be sufficient for a
2.189 +<code>OpenIDRedirectResource</code> object to be configured as described above,
2.190 +making sure that the <code>login_url</code> actually refers to the location of
2.191 +the existing login application.</p>
2.192 +
2.193 +<p>However, if no existing login application (or resource) exists, one may be
2.194 +deployed using adapter code similar to the following:</p>
2.195 +
2.196 +<pre>
2.197 +from WebStack.Adapters.BaseHTTPRequestHandler import deploy
2.198 +from WebStack.Resources.OpenIDLogin import OpenIDLoginResource, Authenticator
2.199 +
2.200 +deploy(
2.201 + OpenIDLoginResource( # This is the login application's main resource.
2.202 + app_url="http://localhost:8081" # This is the "bare server" URL.
2.203 + Authenticator( # This provides authentication support.
2.204 + credentials=(
2.205 + (("http://someserver/badger", "badger"), "abc"),
2.206 + (("http://someserver/vole", "vole"), "xyz"),
2.207 + )
2.208 + )
2.209 + ),
2.210 + address=("", 8081)
2.211 +)
2.212 +</pre>
2.213 +
2.214 +<p>The above code merely starts a login application in the
2.215 +BaseHTTPRequestHandler environment at a specific address (which corresponds to
2.216 +that specified in the <code>login_url</code> of the
2.217 +<code>OpenIDRedirectResource</code> used above) and provides an OpenID
2.218 +<code>Authenticator</code> object configured to recognise a number of
2.219 +different users. The user credentials define OpenID identities and
2.220 +corresponding usernames for this login application, together with
2.221 +passwords.</p>
2.222 +
2.223 +<div class="WebStack">
2.224 +<h3>WebStack API - OpenIDLogin.Authenticator Credentials</h3>
2.225 +
2.226 +<p>When initialising an <code>Authenticator</code> object with credentials,
2.227 +the supplied credentials object must support tests on its contents of the
2.228 +following form:</p>
2.229 +
2.230 +<pre>((openid_identity, username), password) in credentials</pre>
2.231 +
2.232 +<p>In other words, the credentials object must either be a sequence of tuples
2.233 +each containing a (openid_identity, username) tuple as its first element and a
2.234 +password as its second element, or it must implement the
2.235 +<code>__contains__</code> method and accept such tuples as arguments to that
2.236 +method.</p> </div>
2.237 +
2.238 +</body>
2.239 +</html>