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. 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. Otherwise, a redirect occurs to an initiation screen provided by an OpenIDInitiationResource which requests the users's OpenID identifier.
  4. The OpenIDInitiationResource object receives any identity information and causes a redirect to the user's OpenID provider.
  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. 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. Upon successful authentication, the user is redirected back to the application, guarded by OpenIDRedirectResource which should let the user gain access.

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.