# 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
A number of modules are provided to support the +OpenID identity standards, and these serve +the following purposes:
+ +OpenIDInitiation
OpenIDLogin
OpenIDRedirect
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.
Similar in many ways to the functioning of the LoginRedirect and Login Modules, when a request +arrives in the application, the following things happen:
+ +OpenIDRedirectResource
examines the transaction
+and attempts to find out whether it identifies a user.get_user
method on the transaction
+object).OpenIDInitiationResource
which requests the users's OpenID
+identifier.OpenIDInitiationResource
object receives any identity
+information and causes a redirect to the user's OpenID provider.OpenIDLoginResource
object which then presents a login form to be
+completed by the user (similar to that provided by the
+LoginResource
class).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.OpenIDRedirectResource
which
+should let the user gain access.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.
The following parameters must be provided when initialising a
+OpenIDRedirectResource
object:
login_url
app_url
resource
authenticator
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
anonymous_username
get_user
method is
+called. By default, anonymous
is used for such users.logout_parameter_name
logout_url
use_logout_redirect
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
See the API documentation for the LoginRedirectResource
class for more details.
See LoginRedirect and Login Modules for +notes on redirection, application-wide authenticators, anonymous users and +logout functionality.
+ +See LoginRedirect and Login Modules for
+pertinent guidance on extending LoginRedirectResource
, since such
+guidance also applies to OpenIDRedirectResource
.
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.
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.