WebStack

Annotated docs/openid-login-redirect.html

778:e9e0d350a6f1
760:5a80ded59a50
2009-12-01 Paul Boddie file changeset files shortlog Changed the readline implementation in the MessageBodyStream class to use the bounded readline capability presumably available on the underlying stream.
paulb@760 1 
<?xml version="1.0" encoding="iso-8859-1"?>
paulb@760 2 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@760 3 
<html xmlns="http://www.w3.org/1999/xhtml"><head>
paulb@760 4 
  <title>OpenID Modules for Initiation, Login and Redirection</title>
paulb@760 5 
  <link href="styles.css" rel="stylesheet" type="text/css" /></head>
paulb@760 6 
<body>
paulb@760 7 
<h1>OpenID Modules for Initiation, Login and Redirection</h1>
paulb@760 8 
 
 paulb@760      9 
<p>A number of modules are provided to support the
 
 paulb@760     10 
<a href="http://openid.net/">OpenID</a> identity standards, and these serve
 
 paulb@760     11 
the following purposes:</p>
 
 paulb@760     12 
 
 paulb@760     13 
<dl>
 
 paulb@760     14 
<dt><code>OpenIDInitiation</code></dt>
 
 paulb@760     15 
<dd>Requests and handles the identity of the user, redirecting them to their
 
 paulb@760     16 
OpenID (identity) provider.</dd>
 
 paulb@760     17 
<dt><code>OpenIDLogin</code></dt>
 
 paulb@760     18 
<dd>Provides basic OpenID provider functionality, allowing users to
 
 paulb@760     19 
authenticate themselves and to be redirected back to the application which
 
 paulb@760     20 
demanded their authentication.</dd>
 
 paulb@760     21 
<dt><code>OpenIDRedirect</code></dt>
 
 paulb@760     22 
<dd>Provides checking of user identity with redirection to the initiation page
 
 paulb@760     23 
for unauthenticated users.</dd>
 
 paulb@760     24 
</dl>
 
 paulb@760     25 
 
 paulb@760     26 
<p>A combination of the functionality in <code>OpenIDInitiation</code> and
 
 paulb@760     27 
<code>OpenIDRedirect</code> should be sufficient for applications to accept
 
 paulb@760     28 
visitors with OpenID identities. With all of the above modules in use, an
 
 paulb@760     29 
application could be self-sufficient in a similar way to that enjoyed through
 
 paulb@760     30 
the use of the normal <a href="login-redirect.html">LoginRedirect and Login
 
 paulb@760     31 
Modules</a>.</p>
 
 paulb@760     32 
 
 paulb@760     33 
<h2>How the Modules Work</h2>
 
 paulb@760     34 
 
 paulb@760     35 
<p>Similar in many ways to the functioning of the <a
 
 paulb@760     36 
href="login-redirect.html">LoginRedirect and Login Modules</a>, when a request
 
 paulb@760     37 
arrives in the application, the following things happen:</p>
 
 paulb@760     38 
 
 paulb@760     39 
<ol>
 
 paulb@760     40 
  <li>The <code>OpenIDRedirectResource</code> examines the transaction
 
 paulb@760     41 
and attempts to find out whether it identifies a user.</li>
 
 paulb@760     42 
  <li>Should sufficient information be present in the transaction, the
 
 paulb@760     43 
user is allowed to access the application and is identified in the
 
 paulb@760     44 
normal way (ie. the <code>get_user</code> method on the transaction
 
 paulb@760     45 
object).</li>
 
 paulb@760     46 
  <li>Otherwise, a redirect occurs to an initiation screen provided by an
 
 paulb@760     47 
<code>OpenIDInitiationResource</code> which requests the users's OpenID
 
 paulb@760     48 
identifier.</li>
 
 paulb@760     49 
  <li>The <code>OpenIDInitiationResource</code> object receives any identity
 
 paulb@760     50 
information and causes a redirect to the user's OpenID provider.</li>
 
 paulb@760     51 
  <li>Where the OpenID provider is hosted by the application infrastructure,
 
 paulb@760     52 
the user is actually redirected to a login screen provided by an
 
 paulb@760     53 
<code>OpenIDLoginResource</code> object which then presents a login form to be
 
 paulb@760     54 
completed by the user (similar to that provided by the
 
 paulb@760     55 
<code>LoginResource</code> class).</li>
 
 paulb@760     56 
  <li>The <code>OpenIDLoginResource</code> object then receives the
 
 paulb@760     57 
completed form information and verifies the identity of the user,
 
 paulb@760     58 
testing the supplied credentials against the credentials database
 
 paulb@760     59 
specified in the deployment of the resource.</li>
 
 paulb@760     60 
  <li>Upon successful authentication, the user is redirected back to
 
 paulb@760     61 
the application, guarded by <code>OpenIDRedirectResource</code> which
 
 paulb@760     62 
should let the user gain access.</li>
 
 paulb@760     63 
</ol>
 
 paulb@760     64 
 
 paulb@760     65 
<h2>Introducing OpenIDRedirectResource</h2>
 
 paulb@760     66 
 
 paulb@760     67 
<p>Like <code>LoginRedirectResource</code>, introducing
 
 paulb@760     68 
<code>OpenIDRedirectResource</code> into an application can be done in the
 
 paulb@760     69 
adapter code, as described in <a href="writing-adapters.html">"Writing
 
 paulb@760     70 
Adapters"</a>. The most significant difference between deploying normal
 
 paulb@760     71 
resources and <code>LoginRedirectResource</code> objects is the special way in
 
 paulb@760     72 
which such objects are initialised and that they themselves contain the actual
 
 paulb@760     73 
resources of the application which provide the real functionality.</p>
 
 paulb@760     74 
 
 paulb@760     75 
<p>Here is what the deployment of <code>OpenIDRedirectResource</code>
 
 paulb@760     76 
objects often looks like:</p>
 
 paulb@760     77 
 
 paulb@760     78 
<pre>
 
 paulb@760     79 
from WebStack.Resources.OpenIDRedirect import OpenIDRedirectResource, OpenIDRedirectAuthenticator
 
 paulb@760     80 
 
 paulb@760     81 
deploy(
 
 paulb@760     82 
    OpenIDRedirectResource(
 
 paulb@760     83 
        login_url="http://localhost:8080/login",
 
 paulb@760     84 
        app_url="http://localhost:8080",
 
 paulb@760     85 
        resource=[some resource object which provides the real application behaviour],
 
 paulb@760     86 
        authenticator=OpenIDRedirectAuthenticator(
 
 paulb@760     87 
            secret_key="horses",
 
 paulb@760     88 
            app_url="http://localhost:8080"
 
 paulb@760     89 
            ),
 
 paulb@760     90 
        anonymous_parameter_name="anonymous",
 
 paulb@760     91 
        logout_parameter_name="logout"
 
 paulb@760     92 
        )
 
 paulb@760     93 
    )
 
 paulb@760     94 
</pre>
 
 paulb@760     95 
 
 paulb@760     96 
<p>Here, the <code>OpenIDRedirectResource</code> uses the same terminology as
 
 paulb@760     97 
the <code>LoginRedirectResource</code> and employs a <code>login_url</code>,
 
 paulb@760     98 
but this actually refers to the URL where the initiation page will be
 
 paulb@760     99 
displayed. In a sense, it is a kind of login page, but where the actual
 
 paulb@760    100 
authentication will take place elsewhere.</p>
 
 paulb@760    101 
 
 paulb@760    102 
<div class="WebStack">
 
 paulb@760    103 
<h3>WebStack API - OpenIDRedirectResource Initialisation</h3>
 
 paulb@760    104 
 
 paulb@760    105 
<p>The following parameters must be provided when initialising a
 
 paulb@760    106 
<code>OpenIDRedirectResource</code> object:</p>
 
 paulb@760    107 
 
 paulb@760    108 
<dl>
 
 paulb@760    109 
  <dt><code>login_url</code></dt>
 
 paulb@760    110 
  <dd>This specifies the location of the initiation resource which requests
 
 paulb@760    111 
identity details from unidentified users.</dd>
 
 paulb@760    112 
  <dt><code>app_url</code></dt>
 
 paulb@760    113 
  <dd>This specifies the location of the application itself - it must
 
 paulb@760    114 
therefore be updated according to where the application is eventually
 
 paulb@760    115 
deployed. This should be the "bare" reference using a protocol, host and port,
 
 paulb@760    116 
not including any path information.</dd>
 
 paulb@760    117 
  <dt><code>resource</code></dt>
 
 paulb@760    118 
  <dd>This provides the resource object which contains the application
 
 paulb@760    119 
code, or at least the entry point into various parts of the application
 
 paulb@760    120 
code.</dd>
 
 paulb@760    121 
  <dt><code>authenticator</code></dt>
 
 paulb@760    122 
  <dd>This provides the authenticator object which decides whether a
 
 paulb@760    123 
user is recognised or not. The special <code>OpenIDRedirectAuthenticator</code>
 
 paulb@760    124 
is recommended and must itself be configured using a <code>secret_key</code>
 
 paulb@760    125 
parameter which is used to protect user-related information exchanged
 
 paulb@760    126 
over the network - the value provided for <code>secret_key</code> must
 
 paulb@760    127 
be unguessable and kept secret from unauthorised individuals. The
 
 paulb@760    128 
<code>app_url</code> used to initialise the authenticator must be the same as
 
 paulb@760    129 
the one provided to the <code>OpenIDRedirectResource</code>.</dd>
 
 paulb@760    130 
</dl>
 
 paulb@760    131 
 
 paulb@760    132 
<p>The following parameters are optional:</p>
 
 paulb@760    133 
<dl>
 
 paulb@760    134 
  <dt><code>anonymous_parameter_name</code></dt>
 
 paulb@760    135 
  <dd>An optional parameter providing the name of a request parameter
 
 paulb@760    136 
(see <a href="parameters.html">"Request Parameters and Uploads"</a>)
 
 paulb@760    137 
which, if specified, permits a user to access an application without
 
 paulb@760    138 
being formally identified. If omitted, all users will be required to
 
 paulb@760    139 
identify themselves explicitly.</dd>
 
 paulb@760    140 
  <dt><code>anonymous_username</code></dt>
 
 paulb@760    141 
  <dd>An optional parameter providing the name given to anonymous users
 
 paulb@760    142 
which is returned when a transaction's <code>get_user</code> method is
 
 paulb@760    143 
called. By default, <code>anonymous</code> is used for such users.</dd>
 
 paulb@760    144 
  <dt><code>logout_parameter_name</code></dt>
 
 paulb@760    145 
  <dd>An optional parameter providing the name of a request parameter
 
 paulb@760    146 
which, if specified, permits a user to log out of an application. If
 
 paulb@760    147 
omitted, no means of logging out will be available, although deleting
 
 paulb@760    148 
browser cookies will probably have the desired effect.</dd>
 
 paulb@760    149 
  <dt><code>logout_url</code></dt>
 
 paulb@760    150 
  <dd>An optional parameter which indicates the location of the
 
 paulb@760    151 
resource visited when a user logs out. By default, the location is a
 
 paulb@760    152 
path to the root resource in the server environment of the application.</dd>
 
 paulb@760    153 
  <dt><code>use_logout_redirect</code></dt>
 
 paulb@760    154 
  <dd>An optional parameter which determines whether users logging out
 
 paulb@760    155 
of an application will be redirected to the <code>logout_url</code> or
 
 paulb@760    156 
not. By default, users are redirected, but if a false value is given
 
 paulb@760    157 
for this parameter, a simple page is presented to the user informing
 
 paulb@760    158 
them of the situation - it is recommended that a subclass of <code>LoginRedirectResource</code>
 
 paulb@760    159 
be employed should more informative pages be required.</dd><dt><code>path_encoding</code></dt><dd>An
 
 paulb@760    160 
optional parameter indicating the character encoding used to generate
 
 paulb@760    161 
(and, in other places, to interpret) URL-encoded character values in
 
 paulb@760    162 
URLs and paths.</dd>
 
 paulb@760    163 
</dl>
 
 paulb@760    164 
 
 paulb@760    165 
<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>
 
 paulb@760    166 
</div>
 
 paulb@760    167 
 
 paulb@760    168 
<h3>Further Notes</h3>
 
 paulb@760    169 
 
 paulb@760    170 
<p>See <a href="login-redirect.html">LoginRedirect and Login Modules</a> for
 
 paulb@760    171 
notes on redirection, application-wide authenticators, anonymous users and
 
 paulb@760    172 
logout functionality.</p>
 
 paulb@760    173 
 
 paulb@760    174 
<h2>Extending OpenIDRedirectResource</h2>
 
 paulb@760    175 
 
 paulb@760    176 
<p>See <a href="login-redirect.html">LoginRedirect and Login Modules</a> for
 
 paulb@760    177 
pertinent guidance on extending <code>LoginRedirectResource</code>, since such
 
 paulb@760    178 
guidance also applies to <code>OpenIDRedirectResource</code>.</p>
 
 paulb@760    179 
 
 paulb@760    180 
<h2>Deploying an OpenIDLogin Application</h2>
 
 paulb@760    181 
 
 paulb@760    182 
<p>In order to provide OpenID login support for a self-sufficient application,
 
 paulb@760    183 
a login application (or resource) must be available to authenticate unidentified
 
 paulb@760    184 
users. It may already be the case that such an application has been deployed
 
 paulb@760    185 
and is available at a certain URL - if so, it should be sufficient for a
 
 paulb@760    186 
<code>OpenIDRedirectResource</code> object to be configured as described above,
 
 paulb@760    187 
making sure that the <code>login_url</code> actually refers to the location of
 
 paulb@760    188 
the existing login application.</p>
 
 paulb@760    189 
 
 paulb@760    190 
<p>However, if no existing login application (or resource) exists, one may be
 
 paulb@760    191 
deployed using adapter code similar to the following:</p>
 
 paulb@760    192 
 
 paulb@760    193 
<pre>
 
 paulb@760    194 
from WebStack.Adapters.BaseHTTPRequestHandler import deploy
 
 paulb@760    195 
from WebStack.Resources.OpenIDLogin import OpenIDLoginResource, Authenticator
 
 paulb@760    196 
 
 paulb@760    197 
deploy(
 
 paulb@760    198 
    OpenIDLoginResource(                # This is the login application's main resource.
 
 paulb@760    199 
        app_url="http://localhost:8081" # This is the "bare server" URL.
 
 paulb@760    200 
        Authenticator(                  # This provides authentication support.
 
 paulb@760    201 
            credentials=(
 
 paulb@760    202 
                (("http://someserver/badger", "badger"), "abc"),
 
 paulb@760    203 
                (("http://someserver/vole", "vole"), "xyz"),
 
 paulb@760    204 
            )
 
 paulb@760    205 
        )
 
 paulb@760    206 
    ),
 
 paulb@760    207 
    address=("", 8081)
 
 paulb@760    208 
)
 
 paulb@760    209 
</pre>
 
 paulb@760    210 
 
 paulb@760    211 
<p>The above code merely starts a login application in the
 
 paulb@760    212 
BaseHTTPRequestHandler environment at a specific address (which corresponds to
 
 paulb@760    213 
that specified in the <code>login_url</code> of the
 
 paulb@760    214 
<code>OpenIDRedirectResource</code> used above) and provides an OpenID
 
 paulb@760    215 
<code>Authenticator</code> object configured to recognise a number of
 
 paulb@760    216 
different users. The user credentials define OpenID identities and
 
 paulb@760    217 
corresponding usernames for this login application, together with
 
 paulb@760    218 
passwords.</p>
 
 paulb@760    219 
 
 paulb@760    220 
<div class="WebStack">
 
 paulb@760    221 
<h3>WebStack API - OpenIDLogin.Authenticator Credentials</h3>
 
 paulb@760    222 
 
 paulb@760    223 
<p>When initialising an <code>Authenticator</code> object with credentials,
 
 paulb@760    224 
the supplied credentials object must support tests on its contents of the
 
 paulb@760    225 
following form:</p>
 
 paulb@760    226 
 
 paulb@760    227 
<pre>((openid_identity, username), password) in credentials</pre>
 
 paulb@760    228 
 
 paulb@760    229 
<p>In other words, the credentials object must either be a sequence of tuples
 
 paulb@760    230 
each containing a (openid_identity, username) tuple as its first element and a
 
 paulb@760    231 
password as its second element, or it must implement the
 
 paulb@760    232 
<code>__contains__</code> method and accept such tuples as arguments to that
 
 paulb@760    233 
method.</p> </div>
 
 paulb@760    234 
 
 paulb@760    235 
</body>
 
 paulb@760    236 
</html>