Document the new digest_algo parameter

David Tulloh

2016-04-20 d7df42ae13a2a9bfb73a76ed96997dad88a794a9

 docs/configuration.rst

@@ -91,8 +91,7 @@
    from repoze.who.interfaces import IChallenger
    from repoze.who.plugins.basicauth import BasicAuthPlugin
    from repoze.who.plugins.auth_tkt import AuthTktCookiePlugin
    from repoze.who.plugins.cookie import InsecureCookiePlugin
    from repoze.who.plugins.form import FormPlugin
    from repoze.who.plugins.redirector import RedirectorPlugin
    from repoze.who.plugins.htpasswd import HTPasswdPlugin

    io = StringIO()
@@ -104,16 +103,14 @@
        return password == hashed
    htpasswd = HTPasswdPlugin(io, cleartext_check)
    basicauth = BasicAuthPlugin('repoze.who')
    auth_tkt = AuthTktCookiePlugin('secret', 'auth_tkt')
    form = FormPlugin('__do_login', rememberer_name='auth_tkt')
    form.classifications = { IIdentifier:['browser'],
                             IChallenger:['browser'] } # only for browser
    identifiers = [('form', form),
                   ('auth_tkt', auth_tkt),
    auth_tkt = AuthTktCookiePlugin('secret', 'auth_tkt', digest_algo="sha512")
    redirector = RedirectorPlugin('/login.html')
    redirector.classifications = {IChallenger:['browser'],} # only for browser
    identifiers = [('auth_tkt', auth_tkt),
                   ('basicauth', basicauth)]
    authenticators = [('auth_tkt', auth_tkt),
                      ('htpasswd', htpasswd)]
    challengers = [('form', form),
    challengers = [('redirector', redirector),
                   ('basicauth', basicauth)]
    mdproviders = []

@@ -138,26 +135,22 @@

The above example configures the repoze.who middleware with:

- Three ``IIdentifier`` plugins (form auth, auth_tkt cookie, and a
  basic auth plugin).  The form auth plugin is set up to fire only
  when the request is a ``browser`` request (as per the combination of
  the request classifier returning ``browser`` and the framework
  checking against the *classifications* attribute of the plugin,
  which limits ``IIdentifier`` and ``IChallenger`` to the ``browser``
  classification only).  In this setup, when "identification" needs to
  be performed, the form auth plugin will be checked first (if the
  request is a browser request), then the auth_tkt cookie plugin, then
  the basic auth plugin.
- Two ``IIdentifier`` plugins (auth_tkt cookie, and a
  basic auth plugin).  In this setup, when "identification" needs to
  be performed, the auth_tkt plugin will be checked first, then
  the basic auth plugin.  The application is responsible for handling
  login via a form:  this view would use the API (via :method:`remember`)
  to generate apprpriate response headers.

- Two ``IAuthenticator`` plugins: the auth_tkt plugin and an htpasswd plugin.
  The auth_tkt plugin performs both ``IIdentifier`` and ``IAuthenticator``
  functions.  The htpasswd plugin is configured with two valid username /
  assword combinations: chris/chris, and admin/admin.  When an username
  password combinations: chris/chris, and admin/admin.  When an username
  and password is found via any identifier, it will be checked against this
  authenticator.

- Two ``IChallenger`` plugins: the form plugin, then the basic auth
  plugin.  The form auth will fire if the request is a ``browser``
- Two ``IChallenger`` plugins: the redirector plugin, then the basic auth
  plugin.  The redirector auth will fire if the request is a ``browser``
  request, otherwise the basic auth plugin will fire.

The rest of the middleware configuration is for values like logging
@@ -184,10 +177,16 @@

To configure :mod:`repoze.who` in Python, using an .INI file, call
the `make_middleware_with_config` entry point, passing the right-hand
application and the path to the confi file ::
application, the global configuration dictionary, and the path to the
config file. The global configuration dictionary is a dictonary passed 
by PasteDeploy. The only key 'make_middleware_with_config' needs is 
'here' pointing to the config file directory. For debugging people
might find it useful to enable logging by adding the log_file argument,
e.g. log_file="repoze_who.log" ::

    from repoze.who.config import make_middleware_with_config
    who = make_middleware_with_config(app, '/path/to/who.ini')
    global_conf = {"here": "."}  # if this is not defined elsewhere
    who = make_middleware_with_config(app, global_conf, 'who.ini')

:mod:`repoze.who`'s configuration file can be pointed to within a PasteDeploy
configuration file ::
@@ -209,12 +208,10 @@
identification plugins.  The htpasswd and sqlusers plugins are
nominated to act as authenticator plugins. ::

    [plugin:form]
    [plugin:redirector]
    # identificaion and challenge
    use = repoze.who.plugins.form:make_plugin
    login_form_qs = __do_login
    rememberer_name = auth_tkt
    form = %(here)s/login_form.html
    use = repoze.who.plugins.redirector:make_plugin
    login_url = /login.html

    [plugin:auth_tkt]
    # identification and authentication
@@ -223,6 +220,7 @@
    cookie_name = oatmeal
    secure = False
    include_ip = False
    digest_algo = sha512

    [plugin:basicauth]
    # identification and challenge
@@ -238,14 +236,20 @@
    [plugin:sqlusers]
    # authentication
    use = repoze.who.plugins.sql:make_authenticator_plugin
    query = "SELECT userid, password FROM users where login = %(login)s;"
    # Note the double %%:  we have to escape it from the config parser in
    # order to preserve it as a template for the psycopg2, whose 'paramstyle'
    # is 'pyformat'.
    query = SELECT userid, password FROM users where login = %%(login)s
    conn_factory = repoze.who.plugins.sql:make_psycopg_conn_factory
    compare_fn = repoze.who.plugins.sql:default_password_compare

    [plugin:sqlproperties]
    name = properties
    use = repoze.who.plugins.sql:make_metadata_plugin
    query = "SELECT firstname, lastname FROM users where userid = %(__userid)s;"
    # Note the double %%:  we have to escape it from the config parser in
    # order to preserve it as a template for the psycopg2, whose 'paramstyle'
    # is 'pyformat'.
    query = SELECT firstname, lastname FROM users where userid = %%(__userid)s
    filter = my.package:filter_propmd
    conn_factory = repoze.who.plugins.sql:make_psycopg_conn_factory

@@ -257,7 +261,6 @@
    [identifiers]
    # plugin_name;classifier_name:.. or just plugin_name (good for any)
    plugins =
          form;browser
          auth_tkt
          basicauth

@@ -271,7 +274,7 @@
    [challengers]
    # plugin_name;classifier_name:.. or just plugin_name (good for any)
    plugins =
          form;browser
          redirector;browser
          basicauth

    [mdproviders]
@@ -279,23 +282,19 @@
          sqlproperties

The basicauth section configures a plugin that does identification and
challenge for basic auth credentials.  The form section configures a
plugin that does identification and challenge (its implementation
defers to the cookie plugin for identification "forget" and "remember"
duties, thus the "identifier_impl_name" key; this is looked up at
runtime).  The auth_tkt section configures a plugin that does
identification for cookie auth credentials, as well as authenticating
challenge for basic auth credentials.  The redirector section configures a
plugin that does challenges.  The auth_tkt section configures a plugin that
does identification for cookie auth credentials, as well as authenticating
them.  The htpasswd plugin obtains its user info from a file.  The sqlusers
plugin obtains its user info from a Postgres database.

The identifiers section provides an ordered list of plugins that are
willing to provide identification capability.  These will be consulted
in the defined order.  The tokens on each line of the ``plugins=`` key
are in the form "plugin_name:requestclassifier_name:..."  (or just
are in the form "plugin_name;requestclassifier_name:..."  (or just
"plugin_name" if the plugin can be consulted regardless of the
classification of the request).  The configuration above indicates
that the system will look for credentials using the form plugin (if
the request is classified as a browser request), then the cookie
that the system will look for credentials using the auth_tkt cookie
identifier (unconditionally), then the basic auth plugin
(unconditionally).

@@ -321,6 +320,6 @@
provide challenger capability.  These will be consulted in the defined
order, so the system will consult the cookie auth plugin first, then
the basic auth plugin.  Each will have a chance to initiate a
challenge.  The above configuration indicates that the form challenger
challenge.  The above configuration indicates that the redirector challenger
will fire if it's a browser request, and the basic auth challenger
will fire if it's not (fallback).