1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/openid-login-redirect.html Thu May 01 21:44:39 2008 +0000
1.3 @@ -0,0 +1,236 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.6 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.7 + <title>OpenID Modules for Initiation, Login and Redirection</title>
1.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.9 +<body>
1.10 +<h1>OpenID Modules for Initiation, Login and Redirection</h1>
1.11 +
1.12 +<p>A number of modules are provided to support the
1.13 +<a href="http://openid.net/">OpenID</a> identity standards, and these serve
1.14 +the following purposes:</p>
1.15 +
1.16 +<dl>
1.17 +<dt><code>OpenIDInitiation</code></dt>
1.18 +<dd>Requests and handles the identity of the user, redirecting them to their
1.19 +OpenID (identity) provider.</dd>
1.20 +<dt><code>OpenIDLogin</code></dt>
1.21 +<dd>Provides basic OpenID provider functionality, allowing users to
1.22 +authenticate themselves and to be redirected back to the application which
1.23 +demanded their authentication.</dd>
1.24 +<dt><code>OpenIDRedirect</code></dt>
1.25 +<dd>Provides checking of user identity with redirection to the initiation page
1.26 +for unauthenticated users.</dd>
1.27 +</dl>
1.28 +
1.29 +<p>A combination of the functionality in <code>OpenIDInitiation</code> and
1.30 +<code>OpenIDRedirect</code> should be sufficient for applications to accept
1.31 +visitors with OpenID identities. With all of the above modules in use, an
1.32 +application could be self-sufficient in a similar way to that enjoyed through
1.33 +the use of the normal <a href="login-redirect.html">LoginRedirect and Login
1.34 +Modules</a>.</p>
1.35 +
1.36 +<h2>How the Modules Work</h2>
1.37 +
1.38 +<p>Similar in many ways to the functioning of the <a
1.39 +href="login-redirect.html">LoginRedirect and Login Modules</a>, when a request
1.40 +arrives in the application, the following things happen:</p>
1.41 +
1.42 +<ol>
1.43 + <li>The <code>OpenIDRedirectResource</code> examines the transaction
1.44 +and attempts to find out whether it identifies a user.</li>
1.45 + <li>Should sufficient information be present in the transaction, the
1.46 +user is allowed to access the application and is identified in the
1.47 +normal way (ie. the <code>get_user</code> method on the transaction
1.48 +object).</li>
1.49 + <li>Otherwise, a redirect occurs to an initiation screen provided by an
1.50 +<code>OpenIDInitiationResource</code> which requests the users's OpenID
1.51 +identifier.</li>
1.52 + <li>The <code>OpenIDInitiationResource</code> object receives any identity
1.53 +information and causes a redirect to the user's OpenID provider.</li>
1.54 + <li>Where the OpenID provider is hosted by the application infrastructure,
1.55 +the user is actually redirected to a login screen provided by an
1.56 +<code>OpenIDLoginResource</code> object which then presents a login form to be
1.57 +completed by the user (similar to that provided by the
1.58 +<code>LoginResource</code> class).</li>
1.59 + <li>The <code>OpenIDLoginResource</code> object then receives the
1.60 +completed form information and verifies the identity of the user,
1.61 +testing the supplied credentials against the credentials database
1.62 +specified in the deployment of the resource.</li>
1.63 + <li>Upon successful authentication, the user is redirected back to
1.64 +the application, guarded by <code>OpenIDRedirectResource</code> which
1.65 +should let the user gain access.</li>
1.66 +</ol>
1.67 +
1.68 +<h2>Introducing OpenIDRedirectResource</h2>
1.69 +
1.70 +<p>Like <code>LoginRedirectResource</code>, introducing
1.71 +<code>OpenIDRedirectResource</code> into an application can be done in the
1.72 +adapter code, as described in <a href="writing-adapters.html">"Writing
1.73 +Adapters"</a>. The most significant difference between deploying normal
1.74 +resources and <code>LoginRedirectResource</code> objects is the special way in
1.75 +which such objects are initialised and that they themselves contain the actual
1.76 +resources of the application which provide the real functionality.</p>
1.77 +
1.78 +<p>Here is what the deployment of <code>OpenIDRedirectResource</code>
1.79 +objects often looks like:</p>
1.80 +
1.81 +<pre>
1.82 +from WebStack.Resources.OpenIDRedirect import OpenIDRedirectResource, OpenIDRedirectAuthenticator
1.83 +
1.84 +deploy(
1.85 + OpenIDRedirectResource(
1.86 + login_url="http://localhost:8080/login",
1.87 + app_url="http://localhost:8080",
1.88 + resource=[some resource object which provides the real application behaviour],
1.89 + authenticator=OpenIDRedirectAuthenticator(
1.90 + secret_key="horses",
1.91 + app_url="http://localhost:8080"
1.92 + ),
1.93 + anonymous_parameter_name="anonymous",
1.94 + logout_parameter_name="logout"
1.95 + )
1.96 + )
1.97 +</pre>
1.98 +
1.99 +<p>Here, the <code>OpenIDRedirectResource</code> uses the same terminology as
1.100 +the <code>LoginRedirectResource</code> and employs a <code>login_url</code>,
1.101 +but this actually refers to the URL where the initiation page will be
1.102 +displayed. In a sense, it is a kind of login page, but where the actual
1.103 +authentication will take place elsewhere.</p>
1.104 +
1.105 +<div class="WebStack">
1.106 +<h3>WebStack API - OpenIDRedirectResource Initialisation</h3>
1.107 +
1.108 +<p>The following parameters must be provided when initialising a
1.109 +<code>OpenIDRedirectResource</code> object:</p>
1.110 +
1.111 +<dl>
1.112 + <dt><code>login_url</code></dt>
1.113 + <dd>This specifies the location of the initiation resource which requests
1.114 +identity details from unidentified users.</dd>
1.115 + <dt><code>app_url</code></dt>
1.116 + <dd>This specifies the location of the application itself - it must
1.117 +therefore be updated according to where the application is eventually
1.118 +deployed. This should be the "bare" reference using a protocol, host and port,
1.119 +not including any path information.</dd>
1.120 + <dt><code>resource</code></dt>
1.121 + <dd>This provides the resource object which contains the application
1.122 +code, or at least the entry point into various parts of the application
1.123 +code.</dd>
1.124 + <dt><code>authenticator</code></dt>
1.125 + <dd>This provides the authenticator object which decides whether a
1.126 +user is recognised or not. The special <code>OpenIDRedirectAuthenticator</code>
1.127 +is recommended and must itself be configured using a <code>secret_key</code>
1.128 +parameter which is used to protect user-related information exchanged
1.129 +over the network - the value provided for <code>secret_key</code> must
1.130 +be unguessable and kept secret from unauthorised individuals. The
1.131 +<code>app_url</code> used to initialise the authenticator must be the same as
1.132 +the one provided to the <code>OpenIDRedirectResource</code>.</dd>
1.133 +</dl>
1.134 +
1.135 +<p>The following parameters are optional:</p>
1.136 +<dl>
1.137 + <dt><code>anonymous_parameter_name</code></dt>
1.138 + <dd>An optional parameter providing the name of a request parameter
1.139 +(see <a href="parameters.html">"Request Parameters and Uploads"</a>)
1.140 +which, if specified, permits a user to access an application without
1.141 +being formally identified. If omitted, all users will be required to
1.142 +identify themselves explicitly.</dd>
1.143 + <dt><code>anonymous_username</code></dt>
1.144 + <dd>An optional parameter providing the name given to anonymous users
1.145 +which is returned when a transaction's <code>get_user</code> method is
1.146 +called. By default, <code>anonymous</code> is used for such users.</dd>
1.147 + <dt><code>logout_parameter_name</code></dt>
1.148 + <dd>An optional parameter providing the name of a request parameter
1.149 +which, if specified, permits a user to log out of an application. If
1.150 +omitted, no means of logging out will be available, although deleting
1.151 +browser cookies will probably have the desired effect.</dd>
1.152 + <dt><code>logout_url</code></dt>
1.153 + <dd>An optional parameter which indicates the location of the
1.154 +resource visited when a user logs out. By default, the location is a
1.155 +path to the root resource in the server environment of the application.</dd>
1.156 + <dt><code>use_logout_redirect</code></dt>
1.157 + <dd>An optional parameter which determines whether users logging out
1.158 +of an application will be redirected to the <code>logout_url</code> or
1.159 +not. By default, users are redirected, but if a false value is given
1.160 +for this parameter, a simple page is presented to the user informing
1.161 +them of the situation - it is recommended that a subclass of <code>LoginRedirectResource</code>
1.162 +be employed should more informative pages be required.</dd><dt><code>path_encoding</code></dt><dd>An
1.163 +optional parameter indicating the character encoding used to generate
1.164 +(and, in other places, to interpret) URL-encoded character values in
1.165 +URLs and paths.</dd>
1.166 +</dl>
1.167 +
1.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>
1.169 +</div>
1.170 +
1.171 +<h3>Further Notes</h3>
1.172 +
1.173 +<p>See <a href="login-redirect.html">LoginRedirect and Login Modules</a> for
1.174 +notes on redirection, application-wide authenticators, anonymous users and
1.175 +logout functionality.</p>
1.176 +
1.177 +<h2>Extending OpenIDRedirectResource</h2>
1.178 +
1.179 +<p>See <a href="login-redirect.html">LoginRedirect and Login Modules</a> for
1.180 +pertinent guidance on extending <code>LoginRedirectResource</code>, since such
1.181 +guidance also applies to <code>OpenIDRedirectResource</code>.</p>
1.182 +
1.183 +<h2>Deploying an OpenIDLogin Application</h2>
1.184 +
1.185 +<p>In order to provide OpenID login support for a self-sufficient application,
1.186 +a login application (or resource) must be available to authenticate unidentified
1.187 +users. It may already be the case that such an application has been deployed
1.188 +and is available at a certain URL - if so, it should be sufficient for a
1.189 +<code>OpenIDRedirectResource</code> object to be configured as described above,
1.190 +making sure that the <code>login_url</code> actually refers to the location of
1.191 +the existing login application.</p>
1.192 +
1.193 +<p>However, if no existing login application (or resource) exists, one may be
1.194 +deployed using adapter code similar to the following:</p>
1.195 +
1.196 +<pre>
1.197 +from WebStack.Adapters.BaseHTTPRequestHandler import deploy
1.198 +from WebStack.Resources.OpenIDLogin import OpenIDLoginResource, Authenticator
1.199 +
1.200 +deploy(
1.201 + OpenIDLoginResource( # This is the login application's main resource.
1.202 + app_url="http://localhost:8081" # This is the "bare server" URL.
1.203 + Authenticator( # This provides authentication support.
1.204 + credentials=(
1.205 + (("http://someserver/badger", "badger"), "abc"),
1.206 + (("http://someserver/vole", "vole"), "xyz"),
1.207 + )
1.208 + )
1.209 + ),
1.210 + address=("", 8081)
1.211 +)
1.212 +</pre>
1.213 +
1.214 +<p>The above code merely starts a login application in the
1.215 +BaseHTTPRequestHandler environment at a specific address (which corresponds to
1.216 +that specified in the <code>login_url</code> of the
1.217 +<code>OpenIDRedirectResource</code> used above) and provides an OpenID
1.218 +<code>Authenticator</code> object configured to recognise a number of
1.219 +different users. The user credentials define OpenID identities and
1.220 +corresponding usernames for this login application, together with
1.221 +passwords.</p>
1.222 +
1.223 +<div class="WebStack">
1.224 +<h3>WebStack API - OpenIDLogin.Authenticator Credentials</h3>
1.225 +
1.226 +<p>When initialising an <code>Authenticator</code> object with credentials,
1.227 +the supplied credentials object must support tests on its contents of the
1.228 +following form:</p>
1.229 +
1.230 +<pre>((openid_identity, username), password) in credentials</pre>
1.231 +
1.232 +<p>In other words, the credentials object must either be a sequence of tuples
1.233 +each containing a (openid_identity, username) tuple as its first element and a
1.234 +password as its second element, or it must implement the
1.235 +<code>__contains__</code> method and accept such tuples as arguments to that
1.236 +method.</p> </div>
1.237 +
1.238 +</body>
1.239 +</html>