Authenticators are special classes which can, in conjunction with -mechanisms in the server environment, judge whether a user of an application +mechanisms in the server environment, judge whether a user of an +application is recognised or not. The process of using authenticators is as follows:
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
+
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).
An authenticator must be defined within your application in order to make +
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 +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.
- -Transaction objects have the following methods for inspecting and -redefining the identity of users:
-get_userset_userget_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.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 environment 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 - see "Users and Authentication" for more information.
Authenticator objects are created in the adapter code - see "Writing Adapters" for more information.
- + href="writing-adapters.html">"Writing Adapters" for more +information.With application-wide authenticators, anonymous access to resources and -applications can be difficult to permit alongside access by specific users, +
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 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 +authentication schemes, mainly because no logout mechanism generally +exists for such schemes.
diff -r 32b0191a49e4 -r 0643717492e2 docs/cookies.html --- a/docs/cookies.html Sat Apr 30 00:22:03 2005 +0000 +++ b/docs/cookies.html Sat Apr 30 20:31:51 2005 +0000 @@ -19,9 +19,17 @@ stored in a cookie and the type of that information (it must be a plain Python string), the mechanism is useful for identifying users or remembering simple things about the operations that the user has been -performing. Some applications use cookies to remember the state -of their user interfaces, such as which parts of a navigational -menu have been opened by the user, for example. +performing. Some uses include: +When Web pages (and other types of content) are sent to and from users of your application, the text will be in some kind of character diff -r 32b0191a49e4 -r 0643717492e2 docs/login-redirect.html --- a/docs/login-redirect.html Sat Apr 30 00:22:03 2005 +0000 +++ b/docs/login-redirect.html Sat Apr 30 20:31:51 2005 +0000 @@ -1,219 +1,198 @@ - - +
The LoginRedirect and Login modules provide a
+
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
+LoginRedirectResource object which determines whether a
+given
transaction contains information identifying the application's user.
When a request arrives in the application, the following things happen:
+When a request arrives in the application, the following things +happen:
LoginRedirectResource examines the transaction and
- attempts to find out whether it identifies a user.get_user method on the transaction object).LoginResource object which then presents a login form to be
- completed by the user.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.LoginRedirectResource which should
- let the user gain access.LoginRedirectResource examines the transaction
+and attempts to find out whether it identifies a user.get_user method on the transaction
+object).LoginResource
+object which then presents a login form to be completed by the user.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.LoginRedirectResource which
+should let the user gain access.The easiest way of introducing LoginRedirectResource objects
+
The easiest way of introducing LoginRedirectResource
+objects
is to do so in the adapter code, as described in "Writing Adapters". The most significant
+ href="writing-adapters.html">"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
+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
+
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 +
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.
-The following parameters must be provided when initialising a
LoginRedirectResource object:
login_urlapp_urlresourceauthenticatorLoginRedirectAuthenticator 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.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_nameanonymous_usernameget_user method is
- called. By default, anonymous is used for such users.get_user method is
+called. By default, anonymous is used for such users.logout_parameter_namelogout_urluse_logout_redirectlogout_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.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.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 +
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 +
In this mechanism, authenticators are employed, but only to verify
+the
credentials of users when LoginResource or
-LoginRedirectResource objects are accessed. Although it should
+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
+classes with LoginAuthenticator may provide a solution to
+this
issue, however.
In order for this authentication mechanism to function in its entirety, a +
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
+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
+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
+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 +
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)
-)
-
+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
+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
+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.
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
+__contains__ method and accept such tuples as arguments to
+that
method.
With the LoginRedirect and Login modules, it is
+
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
+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).
With the LoginRedirect and Login modules, it is
+
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
+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).
Making sure that Web applications are "secure" involves many different -aspects of application design, deployment and administration. This document -covers only the usage of the authentication features of the WebStack API.
- +Making sure that Web applications are "secure" involves many +different +aspects of application design, deployment and administration. This +guide currently only covers the usage of the authentication features of +the WebStack API.
There are two principal methods of introducing authentication and applying +
There are two principal methods of introducing authentication and +applying access control to WebStack applications:
-Here is a comparison of the features of these mechanisms:
- -| @@ -35,22 +31,41 @@ | ||||
| Deployment | -Some Web server configuration required. - Application only requires an additional object for - authentication. |
- An additional login application or resource must be deployed. | +
+
|
+
+
|
|---|---|---|---|---|
| Flexibility | -Possibly inflexible user experience - users may only get the login
- dialogue; probably no logout function. - HTTP-style authentication is well understood and supported when - automating client access. |
- The login and logout activities can be customised to suit the
- appearance of the rest of the application. - Many applications can share the same login application, providing a - "single sign-on" experience and potentially reduced administrative - overhead. |
+
+
|
+
+
|
Various server environments or frameworks do not support sessions
+directly. In order to provide primitive support for sessions within
+WebStack upon such frameworks, the WebStack.Helpers.Session
+module is used to provide a simple file-based session store. Before
+deploying an application on one of these frameworks, it is necessary to
+create a directory called WebStack-sessions in a
+particular location so that the storage of session information will
+work.
The location of the WebStack-sessions directory
+depends on the framework as summarised below:
| Server Environment | +Directory Location | +
|---|---|
| BaseHTTPRequestHandler | +The directory where the +server is run. | +
| CGI | +The directory where the +handler resides. | +
| mod_python | +The server root (such
+as /usr/local/apache2). |
+
| Twisted | +The directory where the +server is run. | +
Note that the WebStack-sessions directory must
+have the appropriate ownership and privileges necessary for the server
+or framework to write session information into it.
+
Unlike cookies, session information is always stored on the server +and is not communicated back to the user. Consequently, sessions have +several advantages over cookies, and the uses of sessions may include +the storage of...
+In WebStack, a session appears as a dictionary to applications and +is acquired for a specific user through the transaction +object. The following methods are provided in the transaction for +accessing and maintenance of session information:
+get_sessioncreate
+parameter can be set to a true value to create a new session for a user
+if no session previously existed; otherwise None is
+returned in such situations.expire_sessionget_session
+method may still return the current session.Session objects, which resemble dictionaries, employ plain Python +strings as keys in the accessing of information, and as the values +loaded and stored inside the session. Unlike cookies, upon setting +information within a session, such information is remembered thereafter +without any other actions being necessary to make that information +permanent or persistent.
+To find out if a session has already been created, ask for a session +by specifying that one should not be automatically created:
+# In the respond method...+
session = trans.get_session(create=0) # session is None if no session already exists
To ensure that a session exists, just ask for a session:
+# In the respond method...+
session = trans.get_session() # this is the same as using create=1
Session contents may mostly be accessed like dictionaries, so to +access the keys within a session the following code could be used:
+# In the respond method after obtaining a session...+
for key in session.keys():
[Do something with the key - perhaps obtain values.]
To test the presence of a key, and to access values associated with +a key, the usual dictionary methods apply:
+# In the respond method after obtaining the session...+
if session.has_key("my_data"):
my_data = session["my_data"]
[Do something with my_data.]
session["my_data"] = my_data
The session for the user may be removed or "expired" as follows:
+# In the respond method...+
trans.expire_session()
Note that WebStack automatically knows which session is to be +expired since only one such session can exist for the identified user.
+ + diff -r 32b0191a49e4 -r 0643717492e2 docs/sessions.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/sessions.html Sat Apr 30 20:31:51 2005 +0000 @@ -0,0 +1,67 @@ + + + + +The term "session" is a technical term describing information which +is remembered by an application for a particular user. Sessions work in +conjunction which other mechanisms - typically cookies +and user identifiers - like this:
+Information can be said to be "persistent" when it is +remembered beyond the lifetime of a particular request to an +application. Sessions, meanwhile, are effectively a special case of +persistent information - data is addressed or accessed using each +user's identity, and the information is partitioned in such a way that +sessions cannot be shared between users.
+| + | Sessions | +Persistent Information | +
|---|---|---|
| Access | +Through user identity. | +Through any relevant +concept: users, documents, orders, products, locations - anything an +application might want to remember. | +
| Partitioning | +By user identity. Each +user has its own private data store. | +Arbitrary. Many data +stores or data sources may be set up. The data may be shared across the +entire application or there may be access controls in place. | +
Access to persistent information in general can be done by using +database access libraries, for example - see "Integrating +with Other Systems" for more details.
+One way of discovering the identity of the user sending a request +into your application is to test the identity using methods on the +transaction object. Before this can be made to work, you must set +up authentication for your application, as described in "Securing a WebStack Application". Once +authentication is working, every request that arrives in the +application will have the identity of the user attached automatically.
+Having access to a user's identity can be useful in making decisions +about which operations that user is able to perform within your +application. Moreover, the user identity provided by authentication +mechanisms can tell you more about who that user is, as opposed to +typical session information which, on its own, can only really confirm +that the user in question has visited the application before.
+Transaction objects have the following methods for inspecting and +redefining the identity of users:
+get_userset_userget_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.