narr.rst 2.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354
  1. :mod:`repoze.who` Narrative Documentation
  2. =========================================
  3. Using :mod:`repoze.who` as WSGI Middleware
  4. ------------------------------------------
  5. :mod:`repoze.who` was originally developed for use as authentication
  6. middleware in a WSGI pipeline, for use by applications which only
  7. needed to obtain an "authenticated user" to enforce a given security
  8. policy.
  9. See :ref:`middleware_responsibilities` for a description of this use case.
  10. Using :mod:`repoze.who` without WSGI Middleware
  11. -----------------------------------------------
  12. Some applications might want to use a configured set of
  13. :mod:`repoze.who` plugins to do identification and authentication for
  14. a request, outside the context of using :mod:`repoze.who` middleware.
  15. For example, a performance-sensitive application might wish to defer
  16. the effort of identifying and authenticating a user until the point at
  17. which authorization is required, knowing that some code paths will not
  18. need to do the work.
  19. See :ref:`api_narrative` for a description of this use case.
  20. Mixing Middleware and API Uses
  21. ------------------------------
  22. Some applications might use the :mod:`repoze.who` middleware for most
  23. authentication purposes, but need to participate more directly in the
  24. mechanics of identification and authorization for some portions of the
  25. application. For example, consider a system which allows users to
  26. sign up online for membrship in a site: once the user completes
  27. registration, such an application might wish to log the user in
  28. transparently, and thus needs to interact with the configured
  29. :mod:`repoze.who` middleware to generate response headers, ensuring
  30. that the user's next request is properly authenticated.
  31. See :ref:`middleware_api_hybrid` for a description of this use case.
  32. Configuring :mod:`repoze.who`
  33. -----------------------------
  34. Developers and integrators can configure :mod:`repoze.who` using either
  35. imperative Python code (see :ref:`imperative_configuration`) or using an
  36. INI-style declarative configuration file (see :ref:`declarative_configuration`).
  37. In either case, the result of the configuration will be a
  38. :class:`repoze.who.api:APIFactory` instance, complete with a request
  39. classifier, a challenge decider, and a set of plugins for each plugin
  40. interface.