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> |