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