[Repoze-checkins] r736 - in repoze.pam/trunk: . repoze/pam/etc
Chris McDonough
chrism at agendaless.com
Tue Feb 26 02:27:39 UTC 2008
Author: Chris McDonough <chrism at agendaless.com>
Date: Mon Feb 25 21:27:38 2008
New Revision: 736
Log:
Update docs to be in line with the real world.
Modified:
repoze.pam/trunk/README.txt
repoze.pam/trunk/repoze/pam/etc/sample-config.ini
Modified: repoze.pam/trunk/README.txt
==============================================================================
--- repoze.pam/trunk/README.txt (original)
+++ repoze.pam/trunk/README.txt Mon Feb 25 21:27:38 2008
@@ -29,8 +29,9 @@
the request to continue to a downstream WSGI application.
repoze.pam's middleware has one major function on egress: it
- examines the headers set by the downstream application or the WSGI
- environment and conditionally challenges for credentials.
+ examines the headers set by the downstream application, the WSGI
+ environment, or headers supplied by other plugins and conditionally
+ challenges for credentials.
PasteDeploy Configuration
@@ -43,30 +44,20 @@
Classifiers
- repoze.pam "classifies" both the request (on middleware ingress) and
- the response (on middleware egress).
-
- Request classification happens on middleware ingress, before
- extraction and authentication. A request from a browser might be
- classified a different way that a request from an XML-RPC client.
- repoze.pam uses request classifiers to decide which other components
- to consult during subsequent identification and authentication,
- steps. Extraction and authenticator plugins are free to advertise
- themselves as willing to participate in identification and
- authorization for a request based on this classification.
-
- Response classification happens on middleware egress, before
- challenge. A response from a an application can be classified
- arbitrarily. repoze.pam uses response classifiers to decide which
- challenge plugins are willing to examine the response, and
- potentially actuate a challenge. Challenge plugins are free to
- advertise themselves as willing to participate based on the response
+ repoze.pam "classifies" the request on middleware ingress. Request
+ classification happens before identification and authentication. A
+ request from a browser might be classified a different way that a
+ request from an XML-RPC client. repoze.pam uses request classifiers
+ to decide which other components to consult during subsequent
+ identification, authentication, and challenge steps. Plugins are
+ free to advertise themselves as willing to participate in
+ identification and authorization for a request based on this
classification.
- The classification system is pluggable. repoze.pam provides a set
- of default classifiers that you may use. You may extend the
- classification system by making repoze.pam aware of different
- classifier implementations.
+ The classification system is pluggable. repoze.pam provides a
+ default classifier that you may use. You may extend the
+ classification system by making repoze.pam aware of a different
+ classifier implementation.
Plugins
@@ -91,67 +82,65 @@
The WSGI environment is examined and the request is classified
into one "type" of request. The callable named as
- 'request_classifer=' within the '[classifiers]' section is used
- to perform the classification. It returns a value that is
+ 'request_classifer=' within the '[general]' section is used to
+ perform the classification. It returns a value that is
considered to be the request classification.
- 2. Extraction
+ 2. Identification
- Extractors which nominate themselves as willing to extract data
+ Identifiers which nominate themselves as willing to extract data
for a particular class of request (as provided by the request
classifier) will be consulted to retrieve login and password
- data from the environment. For example, a basic auth extractor
- might use the WWW-Authenticate header to find login and password
- information.
+ data from the environment. For example, a basic auth identifier
+ might use the HTTP_AUTHORIZATION header to find login and
+ password information. Identifiers are also responsible for
+ providing header information to set and remove authentication
+ information in the response.
3. Authentication
Authenticators which nominate themselves as willing to
authenticate for a particular class of request will be consulted
to compare login and password information provided by the
- extraction plugin that returned a set of credentials. For
- example, an htpasswd authenticator might look in a file for a
- user record matching the login. If it finds one, and if the
- password listed in the record matches the password found by the
- extractor, the userid of the user would be returned (which would
- be the same as the login name).
+ identification plugins that returned credentials. For example,
+ an htpasswd authenticator might look in a file for a user record
+ matching any of the identities. If it finds one, and if the
+ password listed in the record matches the password provided by
+ an identity, the userid of the user would be returned (which
+ would be the same as the login name).
Response (Egress) Stages
repoze.pam performs the following operations in the following order
during middleware egress:
- 1. Response Classification
+ 1. Challenge Decision
- The WSGI environment and the headers returned by the downstream
- application are examined and the request is classified into one
- "type" of request. The callable named as 'response_classifer='
- within the '[classifiers]' section is used to perform the
- classification. It returns a value that is considered the
- classification.
+ The WSGI environment and the status and headers returned by the
+ downstream application may be examined to determine whether a
+ challenge is required. Typically, only the status is used (if
+ it starts with "401 ", a challenge is required). This behavior
+ is pluggable.
2. Challenge
Challengers which nominate themselves as willing to execute a
challenge for a particular class of request (as provided by the
- response classifier) will be consulted. The challenger plugins
- can use application-returned headers and the WSGI environment to
- determine what sort of operation should be performed to actuate
- the challenge. For example, if the application sets a 401
- Unauthorized header in the response headers, a challenge plugin
- might redirect the user to a login page by setting additional
- headers in the response headers.
+ classifier) will be consulted. The challenger plugins can use
+ application-returned headers, the WSGI environment, and other
+ items to determine what sort of operation should be performed to
+ actuate the challenge. Challenger plugins also defer to the
+ identifier plugin which provided the identity (if any) to reset
+ credentials at challenge time.
Plugin Types
- Extractor Plugins
+ Identifier Plugins
- You can register a plugin as willing to act as an "extractor". An
- extractor examines the WSGI environment and attempts to extract
- credentials from the environment. These credentials are used by
- authenticator plugins to perform authentication. These
- credentials are conditionally placed into the WSGI environment for
- consumption by downstream applications, as well.
+ You can register a plugin as willing to act as an "identifier".
+ An identifier examines the WSGI environment and attempts to
+ extract credentials from the environment. These credentials are
+ used by authenticator plugins to perform authentication.
Authenticator Plugins
@@ -162,26 +151,29 @@
check the provided credentials against the stored data, and return
a user id if the credentials can be validated.
- The user id found by repoze.pam is eventually passed to downstream
- WSGI applications in the "REMOTE_USER' environment variable.
+ The user id provided by an authenticator is eventually passed to
+ downstream WSGI applications in the "REMOTE_USER' environment
+ variable.
Challenger Plugins
- You may register a plugin as willing to act as an "challenger".
- Challenger plugins are responsible for initiating a challeng" to
- the requesting user. Challenger plugins catch specific exceptions
- raised by downstream applications and tun the exception into a
- challenge, which might consist of displaying a form or presenting
- the user with a basic or digest authentication dialog.
+ You may register a plugin as willing to act as a "challenger".
+ Challenger plugins are responsible for initiating a challenge to
+ the requesting user. Challenger plugins are invoked by repoze.pam
+ when it decides a challenge is necessary. A challenge might
+ consist of displaying a form or presenting the user with a basic
+ or digest authentication dialog.
Configuration File Example
repoze.pam is configured using a ConfigParser-style .INI file. The
- configuration file has four main types of sections: plugin sections,
- an authenticators section, a challengers section, and an extractors
- section. Each "plugin" section defines a configuration for a
- particular plugin. The classifiers, authenticators, and extractors
- sections refer to these plugins to form a site configuration.
+ configuration file has five main types of sections: plugin sections,
+ a general section, an identifiers section, an authenticators section,
+ and a challengers section. Each "plugin" section defines a
+ configuration for a particular plugin. The identifiers,
+ authenticators, and challengers sections refer to these plugins to
+ form a site configuration. The general section is general middleware
+ configuration.
Example repoze.pam Configuration File
@@ -189,78 +181,85 @@
configure the repoze.pam middleware. A set of plugins are defined,
and they are referred to by following non-plugin sections.
- In the below configuration, four plugins are defined. The
- cookieauth and basicauth plugins are nominated to act as both
- challenger and extractor plugins. The filusers and sqlusers plugins
- are nominated to act as authenticator plugins.
+ In the below configuration, five plugins are defined. The form, and
+ basicauth plugins are nominated to act as challenger plugins. The
+ form, cookie, and basicauth plugins are nominated to act as
+ identification plugins. The htpasswd and sqlusers plugins are
+ nominated to act as authenticator plugins.
+
+ [plugin:form]
+ # identificaion and challenge
+ login_form_qs = __do_login
+ identifier_impl_name = cookie
+
+ [plugin:cookie]
+ # identification
+ use = egg:repoze.pam#cookie
+ cookie_name = repoze.pam.auth
[plugin:basicauth]
- # challenge and extraction
+ # identification and challenge
use = egg:repoze.pam#basicauth
- # challenge
realm = repoze
- [plugin:cookieauth]
- # challenge and extraction
- use = egg:repoze.pam#cookieauth
- login_path = /login_form
- cookie_name = repoze.pam.auth
- form_name_name = __ac_name
- form_password_name = __ac_password
-
- [plugin:fileusers]
+ [plugin:htpasswd]
# authentication
- use = egg:repoze.pam#fileusersource
- filename = %(here)s/users.txt
- encryptpwd = egg:repoze.pam#shaencrypt
+ use = egg:repoze.pam#htpasswd
+ filename = %(here)s/users.htpasswd
+ check_fn = egg:repoze.pam#crypt_check
[plugin:sqlusers]
# authentication
use = egg:repoze.pam#squsersource
db = sqlite://database?user=foo&pass=bar
get_userinfo = select id, password from users
- encryptpwd = egg:repoze.pam#shaencrypt
+ check_fn = egg:repoze.pam#crypt_check
- [classifiers]
+ [general]
request_classifier = egg:repoze.pam#defaultrequestclassifier
- response_classifier = egg:repoze.pam#defaultresponseclassifier
+ challenge_decider = egg:repoze.pam#defaultchallengedecider
- [extractors]
- # plugin_name:requestclassifier_name:.. or just plugin_name (good for any)
+ [identifiers]
+ # plugin_name:classifier_name:.. or just plugin_name (good for any)
plugins =
- cookieauth:browser
+ form:browser
+ cookie
basicauth
[authenticators]
- # plugin_name:requestclassifier_name.. or just plugin_name (good for any)
+ # plugin_name:classifier_name.. or just plugin_name (good for any)
plugins =
- fileusers
+ htpasswd
sqlusers
[challengers]
- # plugin_name:responseclassifier_name:.. or just plugin_name (good for any)
+ # plugin_name:classifier_name:.. or just plugin_name (good for any)
plugins =
- cookieauth:browser
+ form:browser
basicauth
Further Description of Example Config
- The basicauth section configures a plugin that does extraction and
- challenge for basic auth credentials. The cookieauth section
- configures a plugin that does extraction and challenge for cookie
- auth credentials. The fileusers plugin obtains its user info from a
- file. The sqlusers plugin obtains its user info from a sqlite
- database.
-
- The extractors section provides an ordered list of plugins that are
- willing to provide extraction capability. These will be consulted
- in the defined order. The tokens on each line of the plugin= key
- are in the form "plugin_name:requestclassifier_name" (or just
- "plugin_name" if the plugin can be consulted regardless of the
- classification of the request). The configuration above indicates
- that the system will look for credentials using the cookie auth
- plugin (if the request is classified as a browser request), then the
- basic auth plugin (unconditionally).
+ The basicauth section configures a plugin that does identification
+ and challenge for basic auth credentials. The form section
+ configures a plugin that does identification and challenge (its
+ implementation defers to the cookie plugin for identification
+ "forget" and "remember" duties, thus the "identifier_impl_name" key;
+ this is looked up at runtime). The cookie section configures a
+ plugin that does identification for cookie auth credentials. The
+ htpasswd plugin obtains its user info from a file. The sqlusers
+ plugin obtains its user info from a sqlite database.
+
+ The identifiers section provides an ordered list of plugins that are
+ willing to provide identification capability. These will be
+ consulted in the defined order. The tokens on each line of the
+ 'plugins=' key are in the form
+ "plugin_name:requestclassifier_name:..." (or just "plugin_name" if
+ the plugin can be consulted regardless of the classification of the
+ request). The configuration above indicates that the system will
+ look for credentials using the form plugin (if the request is
+ classified as a browser request), then the cookie identifier
+ (unconditionally), then the basic auth plugin (unconditionally).
The authenticators section provides an ordered list of plugins that
provide authenticator capability. These will be consulted in the
@@ -268,16 +267,18 @@
in the sql database when attempting to validate credentials. No
classification prefixes are given to restrict which of the two
plugins are used, so both plugins are consulted regardless of the
- classification of the request.
+ classification of the request. Each authenticator is called with
+ each set of identities found by the identifier plugins. The first
+ identity that can be authenticated is used to set "REMOTE_USER".
The challengers section provides an ordered list of plugins that
provide challenger capability. These will be consulted in the
defined order, so the system will consult the cookie auth plugin
first, then the basic auth plugin. Each will have a chance, based
on the response classification, to initiate a challenge. The above
- configuration indicates that the cookieauth challenger will fire if
- it's a browser request, and the basic auth challenger will fire if
- it's not (fallback).
+ configuration indicates that the form challenger will fire if it's a
+ browser request, and the basic auth challenger will fire if it's not
+ (fallback).
Interfaces
Modified: repoze.pam/trunk/repoze/pam/etc/sample-config.ini
==============================================================================
--- repoze.pam/trunk/repoze/pam/etc/sample-config.ini (original)
+++ repoze.pam/trunk/repoze/pam/etc/sample-config.ini Mon Feb 25 21:27:38 2008
@@ -1,49 +1,50 @@
+[plugin:form]
+# identificaion and challenge
+login_form_qs = __do_login
+identifier_impl_name = cookie
+
+[plugin:cookie]
+# identification
+use = egg:repoze.pam#cookie
+cookie_name = repoze.pam.auth
+
[plugin:basicauth]
-# the basicauth plugin performs challenge and extraction
+# identification and challenge
use = egg:repoze.pam#basicauth
-# challenge
realm = repoze
-[plugin:cookieauth]
-# the cookieauth plugin performs challenge and extraction
-use = egg:repoze.pam#cookieauth
-login_path = /login_form
-cookie_name = repoze.pam.auth
-form_name_name = __ac_name
-form_password_name = __ac_password
-
-[plugin:fileusers]
-# the fileusers plugin performs authentication
-use = egg:repoze.pam#fileusersource
-filename = %(here)s/users.txt
-encryptpwd = egg:repoze.pam#shaencrypt
+[plugin:htpasswd]
+# authentication
+use = egg:repoze.pam#htpasswd
+filename = %(here)s/users.htpasswd
+check_fn = egg:repoze.pam#crypt_check
[plugin:sqlusers]
-# the sqlusers plugin performs authentication
+# authentication
use = egg:repoze.pam#squsersource
db = sqlite://database?user=foo&pass=bar
get_userinfo = select id, password from users
-encryptpwd = egg:repoze.pam#shaencrypt
+check_fn = egg:repoze.pam#crypt_check
-[classifiers]
+[general]
request_classifier = egg:repoze.pam#defaultrequestclassifier
-response_classifier = egg:repoze.pam#defaultresponseclassifier
+challenge_decider = egg:repoze.pam#defaultchallengedecider
-[extractors]
-# plugin_name:requestclassifier_result:... or just plugin_name (good for any)
+[identifiers]
+# plugin_name:classifier_name:.. or just plugin_name (good for any)
plugins =
- cookieauth:browser
+ form:browser
+ cookie
basicauth
[authenticators]
-# plugin_name:requestclassifier_result:... or just plugin_name (good for any)
+# plugin_name:classifier_name.. or just plugin_name (good for any)
plugins =
- fileusers
+ htpasswd
sqlusers
[challengers]
-# plugin_name:responseclassifier_result:.. or just plugin_name (good for any)
+# plugin_name:classifier_name:.. or just plugin_name (good for any)
plugins =
- cookieauth:browser
+ form:browser
basicauth
-
More information about the Repoze-checkins
mailing list