.. _using_middleware:

Using :mod:`repoze.who` Middleware
==================================

.. _middleware_responsibilities:

Middleware Responsibilities
---------------------------

:mod:`repoze.who` as middleware has one major function on ingress: it
conditionally places identification and authentication information
(including a ``REMOTE_USER`` value) into the WSGI environment and
allows the request to continue to a downstream WSGI application.

:mod:`repoze.who` as middleware has one major function on egress: it
examines the headers set by the downstream application, the WSGI
environment, or headers supplied by other plugins and conditionally
challenges for credentials.


.. _request_lifecycle:

Lifecycle of a Request
----------------------

:mod:`repoze.who` performs duties both on middleware "ingress" and on
middleware "egress". The following graphic outlines where it sits in the context
of the request and its response:

.. image:: .static/request-lifecycle.png


.. _ingress_stages:

Request (Ingress) Stages
++++++++++++++++++++++++

.. image:: .static/ingress.png

:mod:`repoze.who` performs the following operations in the following
order during middleware ingress:

#.  Environment Setup

    The middleware adds a number of keys to the WSGI environment:

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

    ``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 identifier for a particular class of
    request is called to extract identity data ("credentials") from the
    WSGI environment.
 
    For example, a basic auth identifier might use
    the ``HTTP_AUTHORIZATION`` header to find login and password
    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).

#.  Authentication

    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).  Successfully-authenticated ndenties are
    "weighted", with the highest weight identity governing the remainder of
    the request.

#.  Metadata Assignment

    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:

Response (Egress) Stages
++++++++++++++++++++++++

:mod:`repoze.who` performs the following operations in the following
order during middleware egress:

#.  Challenge Decision

    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 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
    
    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.

#.  Remember

    The identifier plugin that the "best" set of credentials came from
    (if any) will be consulted to "remember" these credentials if the
    challenge decider returns False.