Document the new digest_algo parameter

David Tulloh

2016-04-20 d7df42ae13a2a9bfb73a76ed96997dad88a794a9

 docs/plugins.rst

@@ -55,6 +55,8 @@
authentication dialog.


.. _default_plugins:

Default Plugin Implementations
------------------------------

@@ -67,7 +69,8 @@

  An :class:`AuthTktCookiePlugin` is an ``IIdentifier`` and ``IAuthenticator``
  plugin which remembers its identity state in a client-side cookie.
  This plugin uses the ``paste.auth.auth_tkt``"auth ticket" protocol.
  This plugin uses the ``paste.auth.auth_tkt``"auth ticket" protocol and
  is compatible with Apache's mod_auth_tkt.
  It should be instantiated passing a *secret*, which is used to encrypt the
  cookie on the client side and decrypt the cookie on the server side.
  The cookie name used to store the cookie value can be specified
@@ -86,6 +89,20 @@
   <http://westpoint.ltd.uk/advisories/Paul_Johnston_GSEC.pdf>`_ reports
   that as many as 3% of users change their IP addresses legitimately
   during a session.
   
.. note::
   Plugin supports remembering user data in the cookie by saving user dict into ``identity['userdata']``
   parameter of ``remember`` method. They are sent unencrypted and protected by checksum.
   Data will then be returned every time by ``identify``. This dict must be compatible with
   ``urllib.urlencode`` function (``urllib.urlparse.urlencode`` in python 3).
   Saving keys/values with unicode characters is supported only under python 3.

.. note::
   Plugin supports multiple digest algorithms. It defaults to md5 to match
   the default for mod_auth_tkt and paste.auth.auth_tkt. However md5 is not
   recommended as there are viable attacks against the hash. Any algorithm
   from the hashlib library can be specified, currently only sha256 and sha512
   are supported by mod_auth_tkt.

.. module:: repoze.who.plugins.basicauth

@@ -98,56 +115,6 @@
  browsers.  It challenges by sending an ``WWW-Authenticate`` header
  to the browser.  The single argument *realm* indicates the basic
  auth realm that should be sent in the ``WWW-Authenticate`` header.

.. module:: repoze.who.plugins.cookie

.. class:: InsecureCookiePlugin(cookie_name)

  A :class:`InsecureCookiePlugin` is an ``IIdentifier`` plugin.  It
  stores identification information in an insecure form (the base64
  value of the username and password separated by a colon) in a
  client-side cookie.  It accepts a single argument named
  *cookie_name*.  This is the cookie name of the cookie used to store
  the identification information.

.. module:: repoze.who.plugins.form

.. class:: FormPlugin(login_form_qs, rememberer_name [, formbody=None [, formcallable=None]])

  A :class:`FormPlugin` is both an ``IIdentifier`` and ``IChallenger``
  plugin.  It intercepts form POSTs to gather identification at
  ingress and conditionally displays a login form at egress if
  challenge is required.  *login_form_qs* is a query string name used
  to denote that a form POST is destined for the form plugin (anything
  unique is fine), *rememberer_name* is the "configuration name" of
  another ``IIdentifier`` plugin that will be used to perform
  ``remember`` and ``forget`` duties for the FormPlugin (it does not
  do these itself).  For example, if you have a cookie identification
  plugin named ``cookie`` defined in your middleware configuration,
  you might set *rememberer_name* to ``cookie``.  *formbody* is a
  literal string that should be displayed as the form body.
  *formcallable* is a callable that will return a form body if
  *formbody* is None.  If both *formbody* and *formcallable* are None,
  a default form is used.

.. class:: RedirectingFormPlugin(login_form_url, login_handler_path, logout_handler_path, rememberer_name)

  A :class:`RedirectingFormPlugin` is both an ``IIdentifier`` and
  ``IChallenger`` plugin.  It intercepts form POSTs to gather
  identification at ingress and conditionally redirects a login form
  at egress if challenge is required (as opposed to the
  :class:`FormPlugin`, it does not handle its own form generation).
  *login_form_url* is a URL that should be redirected to when a
  challenge is required.  *login_handler_path* is the path that the
  form will POST to, signifying that the plugin should gather
  credentials.  *logout_handler_path* is a path that can be called to
  log the current user out when visited. *rememberer_name* is the
  configuration name of another ``IIdentifier`` plugin that will be
  used to perform ``remember`` and ``forget`` duties for the
  RedirectingFormPlugin (it does not do these itself).  For example,
  if you have a cookie identification plugin named ``cookie`` defined
  in your middleware configuration, you might set *rememberer_name* to
  ``cookie``.

.. module:: repoze.who.plugins.htpasswd

@@ -165,6 +132,27 @@
  available for use as a check function (on UNIX) as
  ``repoze.who.plugins.htpasswd:crypt_check``; it assumes the values
  in the htpasswd file are encrypted with the UNIX ``crypt`` function.

.. module:: repoze.who.plugins.redirector

.. class:: RedirectorPlugin(login_url, came_from_param, reason_param, reason_header)

  A :class:`RedirectorPlugin` is an ``IChallenger`` plugin.
  It redirects to a configured login URL at egress if a challenge is
  required .
  *login_url* is the URL that should be redirected to when a
  challenge is required.  *came_from_param* is the name of an optional
  query string parameter:  if configured, the plugin provides the current
  request URL in the redirected URL's query string, using the supplied
  parameter name.  *reason_param* is the name of an optional
  query string parameter:  if configured, and the application supplies
  a header matching *reason_header* (defaulting to
  ``X-Authorization-Failure-Reason``), the plugin includes that reason in
  the query string of the redirected URL, using the supplied parameter name.
  *reason_header* is an optional parameter overriding the default response
  header name (``X-Authorization-Failure-Reason``) which
  the plugin checks to find the application-supplied reason for the challenge.
  *reason_header* cannot be set unless *reason_param* is also set.

.. module:: repoze.who.plugins.sql

@@ -518,3 +506,144 @@
in the environment or identity.  Our plugin adds ``first_name`` and
``last_name`` values to the identity if the userid matches ``chris``
or ``whit``.


Known Plugins for :mod:`repoze.who`
===================================


Plugins shipped with :mod:`repoze.who`
--------------------------------------

See :ref:`default_plugins`.


Deprecated plugins
------------------

The :mod:`repoze.who.deprecatedplugins` distribution bundles the following
plugin implementations which were shipped with :mod:`repoze.who` prior
to version 2.0a3.  These plugins are deprecated, and should only be used
while migrating an existing deployment to replacement versions.

:class:`repoze.who.plugins.cookie.InsecureCookiePlugin`
  An ``IIdentifier`` plugin which stores identification information in an
  insecure form (the base64 value of the username and password separated by
  a colon) in a client-side cookie.  Please use the
  :class:`AuthTktCookiePlugin` instead.

:class:`repoze.who.plugins.form.FormPlugin`

  An ``IIdentifier`` and ``IChallenger`` plugin,  which intercepts form POSTs
  to gather identification at ingress and conditionally displays a login form
  at egress if challenge is required.
  
  Applications should supply their
  own login form, and use :class:`repoze.who.api.API` to authenticate
  and remember users.  To replace the challenger role, please use
  :class:`repoze.who.plugins.redirector.RedirectorPlugin`, configured with
  the URL of your application's login form.

:class:`repoze.who.plugins.form.RedirectingFormPlugin`

  An ``IIdentifier`` and ``IChallenger`` plugin, which intercepts form POSTs
  to gather identification at ingress and conditionally redirects a login form
  at egress if challenge is required.
  
  Applications should supply their
  own login form, and use :class:`repoze.who.api.API` to authenticate
  and remember users.  To replace the challenger role, please use
  :class:`repoze.who.plugins.redirector.RedirectorPlugin`, configured with
  the URL of your application's login form.


Third-party Plugins
-------------------

:class:`repoze.who.plugins.zodb.ZODBPlugin`
    This class implements the :class:`repoze.who.interfaces.IAuthenticator`
    and :class:`repoze.who.interfaces.IMetadataProvider` plugin interfaces
    using ZODB database lookups.  See
    http://pypi.python.org/pypi/repoze.whoplugins.zodb/

:class:`repoze.who.plugins.ldap.LDAPAuthenticatorPlugin`
    This class implements the :class:`repoze.who.interfaces.IAuthenticator`
    plugin interface using the :mod:`python-ldap` library to query an LDAP
    database.  See http://code.gustavonarea.net/repoze.who.plugins.ldap/

:class:`repoze.who.plugins.ldap.LDAPAttributesPlugin`
    This class implements the :class:`repoze.who.interfaces.IMetadataProvider`
    plugin interface using the :mod:`python-ldap` library to query an LDAP
    database.  See http://code.gustavonarea.net/repoze.who.plugins.ldap/

:class:`repoze.who.plugins.friendlyform.FriendlyFormPlugin`
    This class implements the :class:`repoze.who.interfaces.IIdentifier` and 
    :class:`repoze.who.interfaces.IChallenger` plugin interfaces.  It is
    similar to :class:`repoze.who.plugins.form.RedirectingFormPlugin`,
    bt with with additional features:

    - Users are not challenged on logout, unless the referrer URL is a
      private one (but that’s up to the application).

    - Developers may define post-login and/or post-logout pages.

    - In the login URL, the amount of failed logins is available in the
      environ. It’s also increased by one on every login try. This counter
      will allow developers not using a post-login page to handle logins that
      fail/succeed.

    See http://code.gustavonarea.net/repoze.who-friendlyform/ 

:func:`repoze.who.plugins.openid.identifiers.OpenIdIdentificationPlugin`
    This class implements the :class:`repoze.who.interfaces.IIdentifier`,
    :class:`repoze.who.interfaces.IAuthenticator`, and 
    :class:`repoze.who.interfaces.IChallenger` plugin interfaces using OpenId.
    See http://quantumcore.org/docs/repoze.who.plugins.openid/

:func:`repoze.who.plugins.openid.classifiers.openid_challenge_decider`
    This function provides the :class:`repoze.who.interfaces.IChallengeDecider`
    interface using OpenId.  See
    http://quantumcore.org/docs/repoze.who.plugins.openid/

:class:`repoze.who.plugins.use_beaker.UseBeakerPlugin`
    This packkage provids a :class:`repoze.who.interfaces.IIdentifier` plugin
    using :mod:`beaker.session` cache.  See
    http://pypi.python.org/pypi/repoze.who-use_beaker/

:class:`repoze.who.plugins.cas.main_plugin.CASChallengePlugin`
    This class implements the :class:`repoze.who.interfaces.IIdentifier`
    :class:`repoze.who.interfaces.IAuthenticator`, and 
    :class:`repoze.who.interfaces.IChallenger` plugin interfaces using CAS.
    See http://pypi.python.org/pypi/repoze.who.plugins.cas

:class:`repoze.who.plugins.cas.challenge_decider.my_challenge_decider`
    This function provides the :class:`repoze.who.interfaces.IChallengeDecider`
    interface using CAS.  See
    http://pypi.python.org/pypi/repoze.who.plugins.cas/

:class:`repoze.who.plugins.recaptcha.captcha.RecaptchaPlugin`
    This class implements the :class:`repoze.who.interfaces.IAuthenticator`
    plugin interface, using the recaptch API.
    See http://pypi.python.org/pypi/repoze.who.plugins.recaptcha/

:class:`repoze.who.plugins.sa.SQLAlchemyUserChecker`
    User existence checker for
    :class:`repoze.who.plugins.auth_tkt.AuthTktCookiePlugin`, based on
    the SQLAlchemy ORM. See http://pypi.python.org/pypi/repoze.who.plugins.sa/

:class:`repoze.who.plugins.sa.SQLAlchemyAuthenticatorPlugin`
    This class implements the :class:`repoze.who.interfaces.IAuthenticator`
    plugin interface, using the the SQLAlchemy ORM.
    See http://pypi.python.org/pypi/repoze.who.plugins.sa/
    
:class:`repoze.who.plugins.sa.SQLAlchemyUserMDPlugin`
    This class implements the :class:`repoze.who.interfaces.IMetadataProvider`
    plugin interface, using the the SQLAlchemy ORM.
    See http://pypi.python.org/pypi/repoze.who.plugins.sa/

:class:`repoze.who.plugins.formcookie.CookieRedirectingFormPlugin`
    This class implements the :class:`repoze.who.interfaces.IIdentifier` and 
    :class:`repoze.who.interfaces.IChallenger` plugin interfaces, similar
    to :class:`repoze.who.plugins.form.RedirectingFormPlugin`.  The
    plugin tracks the ``came_from`` URL via a cookie, rather than the query
    string.  See http://pypi.python.org/pypi/repoze.who.plugins.formcookie/