Wordsmithery.

Tres Seaver

2010-06-13 488ba304926a473a4c9c6f713bc43734bf8e48c9

Wordsmithery.

 docs/middleware.rst

@@ -41,46 +41,75 @@
:mod:`repoze.who` performs the following operations in the following
order during middleware ingress:

1.  Request Classification
#.  Environment Setup

    The WSGI environment is examined and the request is classified
    into one "type" of request.  The callable named as the
    ``classifer`` argument to the :mod:`repoze.who` middleware
    constructor is used to perform the classification.  It returns a
    value that is considered to be the request classification (a
    single string).
    The middleware adds a number of keys to the WSGI environment:

2.  Identification
    ``repoze.who.plugins``
       A reference to the configured plugin set.

    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 credentials data from
    the environment.  For example, a basic auth identifier might use
    ``repoze.who.logger``
       A reference to the logger configured into the middleware.

    ``repoze.who.application``
       A refererence to the "right-hand" application.  The plugins
       consulted during request classification / identification /
       authentication may replace this application with another
       WSGI application, which will be used for the remainer of the
       current request.

#.  Request Classification

    The middleware hands the WSGI environment to the configured ``classifier``
    plugin, which is responsible for classifying the request into a single
    "type".  This plugin must return a single string value classifying the
    request, e.g., "browser", "xml-rpc", "webdav", etc.

    This classification may serve to filter out plugins consulted later in
    the request.  For instance, a plugin which issued a challenge as an
    HTML form would be inappropriate for use in requests from an XML-RPC
    or WebDAV client.

#.  Identification

    Each plugin configured as an identifiers for a particular class of
    request is called to extract identity data ("credentials") from the
    WSGI enfironment.
 
    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 during egress.
    information.  Each configured identifier plugin is consulted in turn,
    and any non-None identities returned are collected into a list to be
    authenticated.
    
    Identifiers are also responsible for providing header information used
    to set and remove authentication information in the response during
    egress (to "remember" or "forget" the currently-authenticated user).

3.  Authentication
#.  Authentication

    Authenticators which nominate themselves as willing to
    authenticate for a particular class of request will be consulted
    to compare information provided by the 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
    The middlware consults each plugin configured as an authenticators for 
    a particular class of request, to compare credentials extracted by the
    identification plugins to a given policy, or set of valid credentials.
    
    For example, an htpasswd authenticator might look in a file for a user
    record matching any of the extracted credentials.  If it finds one, and
    if the password listed in the record matches the password in the
    identity, the userid of the user would be returned (which would
    be the same as the login name).
    be the same as the login name).  Successfully-authenticated ndenties are
    "weighted", with the highest weight identity governing the remainder of
    the request.

4.  Metadata Provision
#.  Metadata Assignment

    The identity of the authenticated user found during the
    authentication step can be augmented with arbitrary metadata.
    For example, a metadata provider plugin might augment the
    identity with first, middle and last names, or a more
    specialized metadata provider might augment the identity with a
    list of role or group names.
    After identifying and authenticating a user, :mod:`repoze.who` consults
    plugins configured as metadata providers, which may augmented the
    authenticated identity with arbitrary metadata.

    For example, a metadata provider plugin might add the user's first,
    middle and last names to the identity.  A more specialized metadata
    provider might augment the identity with a list of role or group names
    assigned to the user.


.. _egress_stages:
@@ -93,28 +122,35 @@

#.  Challenge Decision

    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
    The middleare examines the WSGI environment and the status and headers
    returned by the downstream application to determine whether a
    challenge is required.  Typically, only the status is used:  if it
    starts with ``401``, a challenge is required, and the challenge
    decider returns True).  This behavior is pluggable.  It is
    replaced by changing the ``challenge_decider`` argument to the
    middleware.  If a challenge is required, the challenge decider
    will return True; if it's not, it will return False.
    decider returns True.
    
    This behavior can be replaced by configuring a different
    ``challenge_decider`` plugin for the middleware.
    
    If a challenge is required, the challenge decider returns True; otherwise,
    it returns False.

#.  Credentials reset, AKA "forgetting"

    If the challenge decider returns True, the middleware first delegates
    to the identifier plugin which provided the currently-authenticated
    identity to "forget" the identity, by adding response headers (e.g., to
    expire a cookie).

#.  Challenge

    If the challenge decider returns True, challengers which nominate
    themselves as willing to execute a challenge for a particular
    class of request (as provided by the classifier) will be
    consulted, and one will be chosen to perform a challenge.  A
    challenger plugin can use application-returned headers, the WSGI
    
    The plugin then consults each of the set of plugins configured as
    challengers for the current request classification:  the first plugin
    which returns a non-None WSGI application will be used perform a
    challenge.
    
    Challenger plugins may use application-returned headers, the WSGI
    environment, and other items to determine what sort of operation
    should be performed to actuate the challenge.  Note that
    :mod:`repoze.who` defers to the identifier plugin which provided the
    identity (if any) to reset credentials at challenge time; this is
    not the responsibility of the challenger.  This is known as
    "forgetting" credentials.
    should be performed to actuate the challenge.

#.  Remember