paulb@333 | 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
paulb@333 | 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
paulb@333 | 3 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@333 | 4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
paulb@333 | 5 | <head> |
paulb@333 | 6 | <title>LoginRedirect and Login Modules</title> |
paulb@333 | 7 | <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@333 | 8 | <link href="styles.css" rel="stylesheet" type="text/css" /> |
paulb@333 | 9 | </head> |
paulb@333 | 10 | |
paulb@333 | 11 | <body> |
paulb@333 | 12 | <h1>LoginRedirect and Login Modules</h1> |
paulb@333 | 13 | |
paulb@333 | 14 | <p>The <code>LoginRedirect</code> and <code>Login</code> modules provide a |
paulb@333 | 15 | "single sign-on" environment for WebStack applications. Unlike the |
paulb@333 | 16 | authenticator-only approach, each application or part of an application |
paulb@333 | 17 | utilising this mechanism must be wrapped inside a |
paulb@333 | 18 | <code>LoginRedirectResource</code> object which determines whether a given |
paulb@333 | 19 | transaction contains information identifying the application's user.</p> |
paulb@333 | 20 | |
paulb@333 | 21 | <h2>How the Modules Work</h2> |
paulb@333 | 22 | |
paulb@333 | 23 | <p>When a request arrives in the application, the following things happen:</p> |
paulb@333 | 24 | <ol> |
paulb@333 | 25 | <li>The <code>LoginRedirectResource</code> examines the transaction and |
paulb@333 | 26 | attempts to find out whether it identifies a user.</li> |
paulb@333 | 27 | <li>Should sufficient information be present in the transaction, the user |
paulb@333 | 28 | is allowed to access the application and is identified in the normal way |
paulb@333 | 29 | (ie. the <code>get_user</code> method on the transaction object).</li> |
paulb@333 | 30 | <li>Otherwise, a redirect occurs to a login screen provided by a |
paulb@333 | 31 | <code>LoginResource</code> object which then presents a login form to be |
paulb@333 | 32 | completed by the user.</li> |
paulb@333 | 33 | <li>The <code>LoginResource</code> object then receives the completed form |
paulb@333 | 34 | information and verifies the identity of the user, testing the supplied |
paulb@333 | 35 | credentials against the credentials database specified in the deployment |
paulb@333 | 36 | of the resource.</li> |
paulb@333 | 37 | <li>Upon successful authentication, the user is redirected back to the |
paulb@333 | 38 | application, guarded by <code>LoginRedirectResource</code> which should |
paulb@333 | 39 | let the user gain access.</li> |
paulb@333 | 40 | </ol> |
paulb@333 | 41 | |
paulb@333 | 42 | <h2>Introducing LoginRedirectResource</h2> |
paulb@333 | 43 | |
paulb@333 | 44 | <p>The easiest way of introducing <code>LoginRedirectResource</code> objects |
paulb@333 | 45 | is to do so in the adapter code, as described in <a |
paulb@333 | 46 | href="writing-adapters.html">"Writing Adapters"</a>. The most significant |
paulb@333 | 47 | difference between deploying normal resources and |
paulb@333 | 48 | <code>LoginRedirectResource</code> objects is the special way in which such |
paulb@333 | 49 | objects are initialised and that they themselves contain the actual resources |
paulb@333 | 50 | of the application which provide the real functionality.</p> |
paulb@333 | 51 | |
paulb@333 | 52 | <p>Here is what the deployment of <code>LoginRedirectResource</code> objects |
paulb@333 | 53 | often looks like:</p> |
paulb@333 | 54 | <pre>from WebStack.Resources.LoginRedirect import LoginRedirectResource, LoginRedirectAuthenticator |
paulb@333 | 55 | |
paulb@333 | 56 | deploy( |
paulb@333 | 57 | LoginRedirectResource( |
paulb@333 | 58 | login_url="http://localhost:8081", |
paulb@333 | 59 | app_url="http://localhost:8080", |
paulb@333 | 60 | resource=[some resource object which provides the real application behaviour], |
paulb@333 | 61 | authenticator=LoginRedirectAuthenticator(secret_key="horses"), |
paulb@333 | 62 | anonymous_parameter_name="anonymous", |
paulb@333 | 63 | logout_parameter_name="logout" |
paulb@333 | 64 | ) |
paulb@333 | 65 | )</pre> |
paulb@333 | 66 | |
paulb@333 | 67 | <p>Certain parts of the resource are configurable, according to which other |
paulb@333 | 68 | services may exist in or alongside the deployed application.</p> |
paulb@333 | 69 | |
paulb@333 | 70 | <div class="WebStack"> |
paulb@333 | 71 | <h3>WebStack API - LoginRedirectResource Initialisation</h3> |
paulb@333 | 72 | |
paulb@333 | 73 | <p>The following parameters must be provided when initialising a |
paulb@333 | 74 | <code>LoginRedirectResource</code> object:</p> |
paulb@333 | 75 | <dl> |
paulb@333 | 76 | <dt><code>login_url</code></dt> |
paulb@333 | 77 | <dd>This specifies the location of the separate login application or |
paulb@333 | 78 | resource which presents a login screen to unidentified users and logs |
paulb@333 | 79 | them in.</dd> |
paulb@333 | 80 | <dt><code>app_url</code></dt> |
paulb@333 | 81 | <dd>This specifies the location of the application itself - it must |
paulb@333 | 82 | therefore be updated according to where the application is eventually |
paulb@333 | 83 | deployed.</dd> |
paulb@333 | 84 | <dt><code>resource</code></dt> |
paulb@333 | 85 | <dd>This provides the resource object which contains the application |
paulb@333 | 86 | code, or at least the entry point into various parts of the application |
paulb@333 | 87 | code.</dd> |
paulb@333 | 88 | <dt><code>authenticator</code></dt> |
paulb@333 | 89 | <dd>This provides the authenticator object which decides whether a user |
paulb@333 | 90 | is recognised or not. The special |
paulb@333 | 91 | <code>LoginRedirectAuthenticator</code> is recommended and must itself |
paulb@333 | 92 | be configured using a <code>secret_key</code> parameter which is used |
paulb@333 | 93 | to protect user-related information exchanged over the network - the |
paulb@333 | 94 | value provided for <code>secret_key</code> must be unguessable and kept |
paulb@333 | 95 | secret from unauthorised individuals.</dd> |
paulb@333 | 96 | <dt><code>anonymous_parameter_name</code></dt> |
paulb@333 | 97 | <dd>An optional parameter providing the name of a request parameter (see |
paulb@333 | 98 | <a href="parameters.html">"Request Parameters and Uploads"</a>) which, |
paulb@333 | 99 | if specified, permits a user to access an application without being |
paulb@333 | 100 | formally identified. If omitted, all users will be required to identify |
paulb@333 | 101 | themselves explicitly.</dd> |
paulb@333 | 102 | <dt><code>anonymous_username</code></dt> |
paulb@333 | 103 | <dd>An optional parameter providing the name given to anonymous users |
paulb@333 | 104 | which is returned when a transaction's <code>get_user</code> method is |
paulb@333 | 105 | called. By default, <code>anonymous</code> is used for such users.</dd> |
paulb@333 | 106 | <dt><code>logout_parameter_name</code></dt> |
paulb@333 | 107 | <dd>An optional parameter providing the name of a request parameter |
paulb@333 | 108 | which, if specified, permits a user to log out of an application. If |
paulb@333 | 109 | omitted, no means of logging out will be available, although deleting |
paulb@333 | 110 | browser cookies will probably have the desired effect.</dd> |
paulb@333 | 111 | <dt><code>logout_url</code></dt> |
paulb@333 | 112 | <dd>An optional parameter which indicates the location of the resource |
paulb@333 | 113 | visited when a user logs out. By default, the location is a path to the |
paulb@333 | 114 | root resource in the server environment of the application.</dd> |
paulb@333 | 115 | <dt><code>use_logout_redirect</code></dt> |
paulb@333 | 116 | <dd>An optional parameter which determines whether users logging out of |
paulb@333 | 117 | an application will be redirected to the <code>logout_url</code> or |
paulb@333 | 118 | not. By default, users are redirected, but if a false value is given |
paulb@333 | 119 | for this parameter, a simple page is presented to the user informing |
paulb@333 | 120 | them of the situation - it is recommended that a subclass of |
paulb@333 | 121 | <code>LoginRedirectResource</code> be employed should more informative |
paulb@333 | 122 | pages be required.</dd> |
paulb@333 | 123 | </dl> |
paulb@333 | 124 | </div> |
paulb@333 | 125 | |
paulb@333 | 126 | <h3>Redirection From/To the Application</h3> |
paulb@333 | 127 | |
paulb@333 | 128 | <p>Some server/framework environments do not permit automatic redirection |
paulb@333 | 129 | back to the application, notably Apache/mod_python. In such cases, a success |
paulb@333 | 130 | screen is presented to the user with a link to the application they were |
paulb@333 | 131 | attempting to access.</p> |
paulb@333 | 132 | |
paulb@333 | 133 | <h3>The Role of Authenticators</h3> |
paulb@333 | 134 | |
paulb@333 | 135 | <p>In this mechanism, authenticators are employed, but only to verify the |
paulb@333 | 136 | credentials of users when <code>LoginResource</code> or |
paulb@333 | 137 | <code>LoginRedirectResource</code> objects are accessed. Although it should |
paulb@333 | 138 | be possible to reuse <a href="authenticators.html">application-wide |
paulb@333 | 139 | authenticator</a> classes in conjunction with <code>LoginResource</code>, |
paulb@333 | 140 | such classes will not provide the additional functionality required to |
paulb@333 | 141 | support the "single sign-on" aspects of this mechanism - mixing in such |
paulb@333 | 142 | classes with <code>LoginAuthenticator</code> may provide a solution to this |
paulb@333 | 143 | issue, however.</p> |
paulb@333 | 144 | |
paulb@333 | 145 | <h2>Deploying a Login Application</h2> |
paulb@333 | 146 | |
paulb@333 | 147 | <p>In order for this authentication mechanism to function in its entirety, a |
paulb@333 | 148 | login application (or resource) must be available to authenticate |
paulb@333 | 149 | unidentified users. It may already be the case that such an application has |
paulb@333 | 150 | been deployed and is available at a certain URL - if so, it should be |
paulb@333 | 151 | sufficient for a <code>LoginRedirectResource</code> object to be configured |
paulb@333 | 152 | as described above, making sure that the <code>login_url</code> actually |
paulb@333 | 153 | refers to the location of the existing login application, and that the |
paulb@333 | 154 | <code>authenticator</code> object's <code>secret_key</code> is consistent |
paulb@333 | 155 | with the way the existing login application has been set up.</p> |
paulb@333 | 156 | |
paulb@333 | 157 | <p>However, if no existing login application (or resource) exists, one may be |
paulb@333 | 158 | deployed using adapter code similar to the following:</p> |
paulb@333 | 159 | <pre>from WebStack.Adapters.BaseHTTPRequestHandler import deploy |
paulb@333 | 160 | from WebStack.Resources.Login import LoginResource, LoginAuthenticator |
paulb@333 | 161 | |
paulb@333 | 162 | deploy( |
paulb@333 | 163 | LoginResource( # This is the login application's main resource. |
paulb@333 | 164 | LoginAuthenticator( # This provides authentication support. |
paulb@333 | 165 | secret_key="horses", |
paulb@333 | 166 | credentials=( |
paulb@333 | 167 | ("badger", "abc"), |
paulb@333 | 168 | ("vole", "xyz"), |
paulb@333 | 169 | ) |
paulb@333 | 170 | ) |
paulb@333 | 171 | ), |
paulb@333 | 172 | address=("", 8081) |
paulb@333 | 173 | )</pre> |
paulb@333 | 174 | |
paulb@333 | 175 | <p>The above code merely starts a login application in the |
paulb@333 | 176 | BaseHTTPRequestHandler environment at a specific address (which corresponds |
paulb@333 | 177 | to that specified in the <code>login_url</code> of the |
paulb@333 | 178 | <code>LoginRedirectResource</code> used above) and provides a |
paulb@333 | 179 | <code>LoginAuthenticator</code> object configured to use a |
paulb@333 | 180 | <code>secret_key</code> (which corresponds to the <code>secret_key</code> |
paulb@333 | 181 | used in the <code>authenticator</code> of the |
paulb@333 | 182 | <code>LoginRedirectResource</code> above) and some user credentials. The user |
paulb@333 | 183 | credentials define which users are to be recognised for applications which |
paulb@333 | 184 | employ this login application, along with the password details of each |
paulb@333 | 185 | user.</p> |
paulb@333 | 186 | |
paulb@333 | 187 | <div class="WebStack"> |
paulb@333 | 188 | <h3>WebStack API - LoginAuthenticator Credentials</h3> |
paulb@333 | 189 | |
paulb@333 | 190 | <p>When initialising a <code>LoginAuthenticator</code> object with |
paulb@333 | 191 | credentials, the supplied credentials object must support tests on its |
paulb@333 | 192 | contents of the following form:</p> |
paulb@333 | 193 | <pre>(username, password) in credentials</pre> |
paulb@333 | 194 | |
paulb@333 | 195 | <p>In other words, the credentials object must either be a sequence of |
paulb@333 | 196 | username and password tuples, or it must implement the |
paulb@333 | 197 | <code>__contains__</code> method and accept such tuples as arguments to that |
paulb@333 | 198 | method.</p> |
paulb@333 | 199 | </div> |
paulb@333 | 200 | |
paulb@333 | 201 | <h2>Anonymous Access</h2> |
paulb@333 | 202 | |
paulb@333 | 203 | <p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is |
paulb@333 | 204 | possible to declare a particular request parameter (see |
paulb@333 | 205 | <code>anonymous_parameter_name</code> above) which must be present in the URL |
paulb@333 | 206 | used to access a particular application for the client to be given anonymous |
paulb@333 | 207 | access. Consequently, anonymous users are then identified specially with a |
paulb@333 | 208 | special username that can also be configured (see |
paulb@333 | 209 | <code>anonymous_username</code> above).</p> |
paulb@333 | 210 | |
paulb@333 | 211 | <h2>Logout Functions</h2> |
paulb@333 | 212 | |
paulb@333 | 213 | <p>With the <code>LoginRedirect</code> and <code>Login</code> modules, it is |
paulb@333 | 214 | possible to declare a particular request parameter (see |
paulb@333 | 215 | <code>logout_parameter_name</code> above) which must be present in the URL |
paulb@333 | 216 | used to access a particular application for the client to be logged out. A |
paulb@333 | 217 | special logout confirmation URL may also be configured (see |
paulb@333 | 218 | <code>logout_url</code> and <code>use_logout_redirect</code> above).</p> |
paulb@333 | 219 | </body> |
paulb@333 | 220 | </html> |