# HG changeset patch # User paulb # Date 1209678279 0 # Node ID 5a80ded59a50293689f004652223fe84b473c72b # Parent 104e051e6024a0518c53b7561affdae94dac8774 [project @ 2008-05-01 21:44:39 by paulb] Separated optional parameters in the Login/LoginRedirect documentation. Added tentative documentation for OpenID initiation/login/redirection. diff -r 104e051e6024 -r 5a80ded59a50 docs/login-redirect.html --- a/docs/login-redirect.html Thu May 01 21:43:42 2008 +0000 +++ b/docs/login-redirect.html Thu May 01 21:44:39 2008 +0000 @@ -75,6 +75,9 @@ parameter which is used to protect user-related information exchanged over the network - the value provided for secret_key must be unguessable and kept secret from unauthorised individuals. + +

The following parameters are optional:

+
anonymous_parameter_name
An optional parameter providing the name of a request parameter (see "Request Parameters and Uploads") diff -r 104e051e6024 -r 5a80ded59a50 docs/openid-login-redirect.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/openid-login-redirect.html Thu May 01 21:44:39 2008 +0000 @@ -0,0 +1,236 @@ + + + + OpenID Modules for Initiation, Login and Redirection + + +

OpenID Modules for Initiation, Login and Redirection

+ +

A number of modules are provided to support the +OpenID identity standards, and these serve +the following purposes:

+ +
+
OpenIDInitiation
+
Requests and handles the identity of the user, redirecting them to their +OpenID (identity) provider.
+
OpenIDLogin
+
Provides basic OpenID provider functionality, allowing users to +authenticate themselves and to be redirected back to the application which +demanded their authentication.
+
OpenIDRedirect
+
Provides checking of user identity with redirection to the initiation page +for unauthenticated users.
+
+ +

A combination of the functionality in OpenIDInitiation and +OpenIDRedirect should be sufficient for applications to accept +visitors with OpenID identities. With all of the above modules in use, an +application could be self-sufficient in a similar way to that enjoyed through +the use of the normal LoginRedirect and Login +Modules.

+ +

How the Modules Work

+ +

Similar in many ways to the functioning of the LoginRedirect and Login Modules, when a request +arrives in the application, the following things happen:

+ +
    +
  1. The OpenIDRedirectResource examines the transaction +and attempts to find out whether it identifies a user.
    2. +
  2. Should sufficient information be present in the transaction, the +user is allowed to access the application and is identified in the +normal way (ie. the get_user method on the transaction +object).
    3. +
  3. Otherwise, a redirect occurs to an initiation screen provided by an +OpenIDInitiationResource which requests the users's OpenID +identifier.
    4. +
  4. The OpenIDInitiationResource object receives any identity +information and causes a redirect to the user's OpenID provider.
    5. +
  5. Where the OpenID provider is hosted by the application infrastructure, +the user is actually redirected to a login screen provided by an +OpenIDLoginResource object which then presents a login form to be +completed by the user (similar to that provided by the +LoginResource class).
    6. +
  6. The OpenIDLoginResource object then receives the +completed form information and verifies the identity of the user, +testing the supplied credentials against the credentials database +specified in the deployment of the resource.
    7. +
  7. Upon successful authentication, the user is redirected back to +the application, guarded by OpenIDRedirectResource which +should let the user gain access.
    8. +
+ +

Introducing OpenIDRedirectResource

+ +

Like LoginRedirectResource, introducing +OpenIDRedirectResource into an application can be done in the +adapter code, as described in "Writing +Adapters". The most significant difference between deploying normal +resources and LoginRedirectResource objects is the special way in +which such objects are initialised and that they themselves contain the actual +resources of the application which provide the real functionality.

+ +

Here is what the deployment of OpenIDRedirectResource +objects often looks like:

+ +
+from WebStack.Resources.OpenIDRedirect import OpenIDRedirectResource, OpenIDRedirectAuthenticator
+
+deploy(
+    OpenIDRedirectResource(
+        login_url="http://localhost:8080/login",
+        app_url="http://localhost:8080",
+        resource=[some resource object which provides the real application behaviour],
+        authenticator=OpenIDRedirectAuthenticator(
+            secret_key="horses",
+            app_url="http://localhost:8080"
+            ),
+        anonymous_parameter_name="anonymous",
+        logout_parameter_name="logout"
+        )
+    )
+
+ +

Here, the OpenIDRedirectResource uses the same terminology as +the LoginRedirectResource and employs a login_url, +but this actually refers to the URL where the initiation page will be +displayed. In a sense, it is a kind of login page, but where the actual +authentication will take place elsewhere.

+ +
+

WebStack API - OpenIDRedirectResource Initialisation

+ +

The following parameters must be provided when initialising a +OpenIDRedirectResource object:

+ +
+
login_url
+
This specifies the location of the initiation resource which requests +identity details from unidentified users.
+
app_url
+
This specifies the location of the application itself - it must +therefore be updated according to where the application is eventually +deployed. This should be the "bare" reference using a protocol, host and port, +not including any path information.
+
resource
+
This provides the resource object which contains the application +code, or at least the entry point into various parts of the application +code.
+
authenticator
+
This provides the authenticator object which decides whether a +user is recognised or not. The special OpenIDRedirectAuthenticator +is recommended and must itself be configured using a secret_key +parameter which is used to protect user-related information exchanged +over the network - the value provided for secret_key must +be unguessable and kept secret from unauthorised individuals. The +app_url used to initialise the authenticator must be the same as +the one provided to the OpenIDRedirectResource.
+
+ +

The following parameters are optional:

+
+
anonymous_parameter_name
+
An optional parameter providing the name of a request parameter +(see "Request Parameters and Uploads") +which, if specified, permits a user to access an application without +being formally identified. If omitted, all users will be required to +identify themselves explicitly.
+
anonymous_username
+
An optional parameter providing the name given to anonymous users +which is returned when a transaction's get_user method is +called. By default, anonymous is used for such users.
+
logout_parameter_name
+
An optional parameter providing the name of a request parameter +which, if specified, permits a user to log out of an application. If +omitted, no means of logging out will be available, although deleting +browser cookies will probably have the desired effect.
+
logout_url
+
An optional parameter which indicates the location of the +resource visited when a user logs out. By default, the location is a +path to the root resource in the server environment of the application.
+
use_logout_redirect
+
An optional parameter which determines whether users logging out +of an application will be redirected to the logout_url or +not. By default, users are redirected, but if a false value is given +for this parameter, a simple page is presented to the user informing +them of the situation - it is recommended that a subclass of LoginRedirectResource +be employed should more informative pages be required.
path_encoding
An +optional parameter indicating the character encoding used to generate +(and, in other places, to interpret) URL-encoded character values in +URLs and paths.
+
+ +

See the API documentation for the LoginRedirectResource class for more details.

+
+ +

Further Notes

+ +

See LoginRedirect and Login Modules for +notes on redirection, application-wide authenticators, anonymous users and +logout functionality.

+ +

Extending OpenIDRedirectResource

+ +

See LoginRedirect and Login Modules for +pertinent guidance on extending LoginRedirectResource, since such +guidance also applies to OpenIDRedirectResource.

+ +

Deploying an OpenIDLogin Application

+ +

In order to provide OpenID login support for a self-sufficient application, +a login application (or resource) must be available to authenticate unidentified +users. It may already be the case that such an application has been deployed +and is available at a certain URL - if so, it should be sufficient for a +OpenIDRedirectResource object to be configured as described above, +making sure that the login_url actually refers to the location of +the existing login application.

+ +

However, if no existing login application (or resource) exists, one may be +deployed using adapter code similar to the following:

+ +
+from WebStack.Adapters.BaseHTTPRequestHandler import deploy
+from WebStack.Resources.OpenIDLogin import OpenIDLoginResource, Authenticator
+
+deploy(
+    OpenIDLoginResource(                # This is the login application's main resource.
+        app_url="http://localhost:8081" # This is the "bare server" URL.
+        Authenticator(                  # This provides authentication support.
+            credentials=(
+                (("http://someserver/badger", "badger"), "abc"),
+                (("http://someserver/vole", "vole"), "xyz"),
+            )
+        )
+    ),
+    address=("", 8081)
+)
+
+ +

The above code merely starts a login application in the +BaseHTTPRequestHandler environment at a specific address (which corresponds to +that specified in the login_url of the +OpenIDRedirectResource used above) and provides an OpenID +Authenticator object configured to recognise a number of +different users. The user credentials define OpenID identities and +corresponding usernames for this login application, together with +passwords.

+ +
+

WebStack API - OpenIDLogin.Authenticator Credentials

+ +

When initialising an Authenticator object with credentials, +the supplied credentials object must support tests on its contents of the +following form:

+ +
((openid_identity, username), password) in credentials
+ +

In other words, the credentials object must either be a sequence of tuples +each containing a (openid_identity, username) tuple as its first element and a +password as its second element, or it must implement the +__contains__ method and accept such tuples as arguments to that +method.

+ + +