# HG changeset patch # User paulb # Date 1113089158 0 # Node ID bd75e0085bda0036b39116da58a703f6515787be # Parent 2430072f2103039c18e91b164c1cf90c6092032a [project @ 2005-04-09 23:25:58 by paulb] Improved the authentication documentation. diff -r 2430072f2103 -r bd75e0085bda docs/authenticators.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/authenticators.html Sat Apr 09 23:25:58 2005 +0000 @@ -0,0 +1,101 @@ + + + + + Application-Wide Authenticators + + + + + +

Application-Wide Authenticators

+ +

Authenticators are special classes which can, in conjunction with +mechanisms in the server environment, judge whether a user of an application +is recognised or not. The process of using authenticators is as follows:

+
    +
  1. Set up authentication in the server environment or framework in which + the application is to be deployed.
    2. +
  2. Introduce an authenticator class in the application.
    3. +
+ +

Setting Up Authentication

+ +

The exact details of configuring authentication mechanisms in each server +environment may vary substantially. For example, Apache environments require +that Auth directives be specified in the Apache configuration +files (see docs/ModPython/NOTES.txt); in Zope environments, +protected folders can be defined to hold the application when deployed (see +docs/Zope/NOTES.txt).

+ +

Defining an Authenticator

+ +

An authenticator must be defined within your application in order to make +decisions about users who have presented their credentials; this +authenticator will respond with a decision when prompted by the server or +underlying framework, either allowing or denying access for the user whose +identity has been presented to the server/framework.

+ +

The code for an authenticator usually looks like this:

+
class MyAuthenticator:
+
+    "This is an authenticator - something which decides whether a user is known to the application."
+
+    def authenticate(self, trans):
+        user = trans.get_user()
+        [Make a decision about the validity of the user.]
+        [Return a true value if the user is allowed to access the application.]
+        [Return a false value if the user is not recognised or allowed to access the application.]
+
+    def get_auth_type(self):
+        "This method returns 'Basic' in most deployments."
+        return "Basic"
+
+    def get_realm(self):
+        "This method returns something to distinguish this authentication mechanism from others."
+        return "MyRealm"
+ +

In this mechanism, authenticators rely on authentication information from +the server/framework and have a "global" effect on access to the application. +However, it is always possible to test the user identity later on and to +change the way an application behaves accordingly.

+ +
+

WebStack API - User Identity

+ +

Transaction objects have the following methods for inspecting and +redefining the identity of users:

+
+
get_user
+
This gets the name of the user attempting to access the + application.
+
set_user
+
This sets the name of the user, thus affecting subsequent calls to + get_user, allowing certain parts of an application to view + users according to other criteria than their basic username - for + example, one might use set_user to redefine each user's + identity in terms of the role that user may have in an application.
+
+
+ +

Introducing an Authenticator

+ +

Authenticator objects are created in the adapter code - see "Writing Adapters" for more information.

+ +

Anonymous Access

+ +

With application-wide authenticators, anonymous access to resources and +applications can be difficult to permit alongside access by specific users, +mostly because servers and frameworks which employ HTTP authentication +schemes do so globally for a given application.

+ +

Logout Functions

+ +

With application-wide authenticators, a logout function may not be +available if the server/framework has been configured to use HTTP +authentication schemes, mainly because no logout mechanism generally exists +for such schemes.

+ + diff -r 2430072f2103 -r bd75e0085bda docs/login-redirect.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/login-redirect.html Sat Apr 09 23:25:58 2005 +0000 @@ -0,0 +1,220 @@ + + + + + LoginRedirect and Login Modules + + + + + +

LoginRedirect and Login Modules

+ +

The LoginRedirect and Login modules provide a +"single sign-on" environment for WebStack applications. Unlike the +authenticator-only approach, each application or part of an application +utilising this mechanism must be wrapped inside a +LoginRedirectResource object which determines whether a given +transaction contains information identifying the application's user.

+ +

How the Modules Work

+ +

When a request arrives in the application, the following things happen:

+
    +
  1. The LoginRedirectResource 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 a login screen provided by a + LoginResource object which then presents a login form to be + completed by the user.
    4. +
  4. The LoginResource 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.
    5. +
  5. Upon successful authentication, the user is redirected back to the + application, guarded by LoginRedirectResource which should + let the user gain access.
    6. +
+ +

Introducing LoginRedirectResource

+ +

The easiest way of introducing LoginRedirectResource objects +is to do so 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 LoginRedirectResource objects +often looks like:

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

Certain parts of the resource are configurable, according to which other +services may exist in or alongside the deployed application.

+ +
+

WebStack API - LoginRedirectResource Initialisation

+ +

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

+
+
login_url
+
This specifies the location of the separate login application or + resource which presents a login screen to unidentified users and logs + them in.
+
app_url
+
This specifies the location of the application itself - it must + therefore be updated according to where the application is eventually + deployed.
+
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 + LoginRedirectAuthenticator 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.
+
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.
+
+
+ +

Redirection From/To the Application

+ +

Some server/framework environments do not permit automatic redirection +back to the application, notably Apache/mod_python. In such cases, a success +screen is presented to the user with a link to the application they were +attempting to access.

+ +

The Role of Authenticators

+ +

In this mechanism, authenticators are employed, but only to verify the +credentials of users when LoginResource or +LoginRedirectResource objects are accessed. Although it should +be possible to reuse application-wide +authenticator classes in conjunction with LoginResource, +such classes will not provide the additional functionality required to +support the "single sign-on" aspects of this mechanism - mixing in such +classes with LoginAuthenticator may provide a solution to this +issue, however.

+ +

Deploying a Login Application

+ +

In order for this authentication mechanism to function in its entirety, 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 LoginRedirectResource object to be configured +as described above, making sure that the login_url actually +refers to the location of the existing login application, and that the +authenticator object's secret_key is consistent +with the way the existing login application has been set up.

+ +

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.Login import LoginResource, LoginAuthenticator
+
+deploy(
+    LoginResource(                   # This is the login application's main resource.
+        LoginAuthenticator(          # This provides authentication support.
+            secret_key="horses",
+            credentials=(
+                ("badger", "abc"),
+                ("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 +LoginRedirectResource used above) and provides a +LoginAuthenticator object configured to use a +secret_key (which corresponds to the secret_key +used in the authenticator of the +LoginRedirectResource above) and some user credentials. The user +credentials define which users are to be recognised for applications which +employ this login application, along with the password details of each +user.

+ +
+

WebStack API - LoginAuthenticator Credentials

+ +

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

+
(username, password) in credentials
+ +

In other words, the credentials object must either be a sequence of +username and password tuples, or it must implement the +__contains__ method and accept such tuples as arguments to that +method.

+
+ +

Anonymous Access

+ +

With the LoginRedirect and Login modules, it is +possible to declare a particular request parameter (see +anonymous_parameter_name above) which must be present in the URL +used to access a particular application for the client to be given anonymous +access. Consequently, anonymous users are then identified specially with a +special username that can also be configured (see +anonymous_username above).

+ +

Logout Functions

+ +

With the LoginRedirect and Login modules, it is +possible to declare a particular request parameter (see +logout_parameter_name above) which must be present in the URL +used to access a particular application for the client to be logged out. A +special logout confirmation URL may also be configured (see +logout_url and use_logout_redirect above).

+ + diff -r 2430072f2103 -r bd75e0085bda docs/securing.html --- a/docs/securing.html Sat Apr 09 23:25:43 2005 +0000 +++ b/docs/securing.html Sat Apr 09 23:25:58 2005 +0000 @@ -1,6 +1,6 @@ + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> Securing a WebStack Application @@ -26,76 +26,10 @@ WebStack.Resources.Login modules. -

Application-Wide Authenticators

- -

First, set up the usage of such authentication mechanisms in the -server/framework environment. For example, introduce Auth -directives in your Apache configuration (see -docs/ModPython/NOTES.txt) or protected folders in your Zope -instance (see docs/Zope/NOTES.txt).

- -

Then, define an authenticator when deploying your application; this -authenticator will respond with a decision when prompted by the server or -underlying framework, either allowing or denying access for the user whose -identity has been presented to the server/framework.

- -

In this mechanism, authenticators rely on authentication information from -the server/framework and have a "global" effect on access to the -application.

- -

LoginRedirect and Login Modules

- -

The LoginRedirect and Login modules provide a -"single sign-on" environment for WebStack applications. Unlike the -authenticator-only approach, each application or part of an application -utilising this mechanism must be wrapped inside a -LoginRedirectResource object which determines whether a given -transaction contains information identifying the application's user.

- -

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). Otherwise, a -redirect occurs to a login screen provided by a LoginResource -object which then presents a login form to be completed by the user.

- -

The LoginResource object verifies the identity of the user, -testing the supplied credentials against the credentials database specified -in the deployment of the resource. Upon successful authentication, the user -is redirected back to the application, which should let the user gain -access.

- -

Some server/framework environments do not permit automatic redirection -back to the application, notably Apache/mod_python. In such cases, a success -screen is presented to the user with a link to the application they were -attempting to access.

- -

In this mechanism, authenticators are employed, but only to verify the -credentials of users when LoginResource or -LoginRedirectResource objects are accessed.

- -

Anonymous Access

- -

With application-wide authenticators, anonymous access to resources and -applications can be difficult to permit alongside access by specific users, -mostly because servers and frameworks which employ HTTP authentication -schemes do so globally for a given application.

- -

With the LoginRedirect and Login modules, it is -possible to declare a particular request parameter which must be present in -the URL used to access a particular application for the client to be given -anonymous access. Consequently, anonymous users are then identified specially -with a special username that can also be configured.

- -

Logout Functions

- -

With application-wide authenticators, a logout function may not be -available if the server/framework has been configured to use HTTP -authentication schemes, since no such function is defined for such -schemes.

- -

With the LoginRedirect and Login modules, it is -possible to declare a particular request parameter which must be present in -the URL used to access a particular application for the client to be logged -out. A special logout confirmation URL may also be configured.

+

Choosing an Authentication Strategy

+