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