.. _configuration_points:

Configuring :mod:`repoze.who`
=============================

Configuration Points
--------------------

Classifiers
+++++++++++

:mod:`repoze.who` "classifies" the request on middleware ingress.
Request classification happens before identification and
authentication.  A request from a browser might be classified a
different way than a request from an XML-RPC client.
:mod:`repoze.who` uses request classifiers to decide which other
components to consult during subsequent identification,
authentication, and challenge steps.  Plugins are free to advertise
themselves as willing to participate in identification and
authorization for a request based on this classification.  The request
classification system is pluggable.  :mod:`repoze.who` provides a
default classifier that you may use.

You may extend the classification system by making :mod:`repoze.who` aware
of a different request classifier implementation.

Challenge Deciders
++++++++++++++++++

:mod:`repoze.who` uses a "challenge decider" to decide whether the
response returned from a downstream application requires a challenge
plugin to fire.  When using the default challenge decider, only the
status is used (if it starts with ``401``, a challenge is required).

:mod:`repoze.who` also provides an alternate challenge decider,
``repoze.who.classifiers.passthrough_challenge_decider``, which avoids
challenging ``401`` responses which have been "pre-challenged" by the
application.

You may supply a different challenge decider as necessary.

Plugins
+++++++

:mod:`repoze.who` has core functionality designed around the concept
of plugins.  Plugins are instances that are willing to perform one or
more identification- and/or authentication-related duties.  Each
plugin can be configured arbitrarily.

:mod:`repoze.who` consults the set of configured plugins when it
intercepts a WSGI request, and gives some subset of them a chance to
influence what :mod:`repoze.who` does for the current request.

.. note:: As of :mod:`repoze.who` 1.0.7, the ``repoze.who.plugins``
   package is a namespace package, intended to make it possible for
   people to ship eggs which are who plugins as,
   e.g. ``repoze.who.plugins.mycoolplugin``.


.. _imperative_configuration:

Configuring :mod:`repoze.who` via Python Code
---------------------------------------------

.. module:: repoze.who.middleware

.. class:: PluggableAuthenticationMiddleware(app, identifiers, challengers, authenticators, mdproviders, classifier, challenge_decider [, log_stream=None [, log_level=logging.INFO[, remote_user_key='REMOTE_USER']]])

  The primary method of configuring the :mod:`repoze.who` middleware is
  to use straight Python code, meant to be consumed by frameworks
  which construct and compose middleware pipelines without using a
  configuration file.

  In the middleware constructor: *app* is the "next" application in
  the WSGI pipeline. *identifiers* is a sequence of ``IIdentifier``
  plugins, *challengers* is a sequence of ``IChallenger`` plugins,
  *mdproviders* is a sequence of ``IMetadataProvider`` plugins.  Any
  of these can be specified as the empty sequence.  *classifier* is a
  request classifier callable, *challenge_decider* is a challenge
  decision callable.  *log_stream* is a stream object (an object with
  a ``write`` method) *or* a ``logging.Logger`` object, *log_level* is
  a numeric value that maps to the ``logging`` module's notion of log
  levels, *remote_user_key* is the key in which the ``REMOTE_USER``
  (userid) value should be placed in the WSGI environment for
  consumption by downstream applications.

An example configuration which uses the default plugins follows::

    from repoze.who.middleware import PluggableAuthenticationMiddleware
    from repoze.who.interfaces import IIdentifier
    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.redirector import RedirectorPlugin
    from repoze.who.plugins.htpasswd import HTPasswdPlugin

    io = StringIO()
    salt = 'aa'
    for name, password in [ ('admin', 'admin'), ('chris', 'chris') ]:
        io.write('%s:%s\n' % (name, password))
    io.seek(0)
    def cleartext_check(password, hashed):
        return password == hashed
    htpasswd = HTPasswdPlugin(io, cleartext_check)
    basicauth = BasicAuthPlugin('repoze.who')
    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 = [('redirector', redirector),
                   ('basicauth', basicauth)]
    mdproviders = []

    from repoze.who.classifiers import default_request_classifier
    from repoze.who.classifiers import default_challenge_decider
    log_stream = None
    import os
    if os.environ.get('WHO_LOG'):
        log_stream = sys.stdout

    middleware = PluggableAuthenticationMiddleware(
        app,
        identifiers,
        authenticators,
        challengers,
        mdproviders,
        default_request_classifier,
        default_challenge_decider,
        log_stream = log_stream,
        log_level = logging.DEBUG
        )

The above example configures the repoze.who middleware with:

- 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 /
  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 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
and the classifier and decider implementations.  These use the "stock"
implementations.

.. note:: The ``app`` referred to in the example is the "downstream"
   WSGI application that who is wrapping.


.. _declarative_configuration:

Configuring :mod:`repoze.who` via Config File
---------------------------------------------

:mod:`repoze.who` may be configured using a ConfigParser-style .INI
file.  The configuration file has five main types of sections: plugin
sections, a general section, an identifiers section, an authenticators
section, and a challengers section.  Each "plugin" section defines a
configuration for a particular plugin.  The identifiers,
authenticators, and challengers sections refer to these plugins to
form a site configuration.  The general section is general middleware
configuration.

To configure :mod:`repoze.who` in Python, using an .INI file, call
the `make_middleware_with_config` entry point, passing the right-hand
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
    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 ::

    [filter:who]
    use = egg:repoze.who#config
    config_file = %(here)s/who.ini
    log_file = stdout
    log_level = debug

Below is an example of a configuration file (what ``config_file``
might point at above ) that might be used to configure the
:mod:`repoze.who` middleware.  A set of plugins are defined, and they
are referred to by following non-plugin sections.

In the below configuration, five plugins are defined.  The form, and
basicauth plugins are nominated to act as challenger plugins.  The
form, cookie, and basicauth plugins are nominated to act as
identification plugins.  The htpasswd and sqlusers plugins are
nominated to act as authenticator plugins. ::

    [plugin:redirector]
    # identificaion and challenge
    use = repoze.who.plugins.redirector:make_plugin
    login_url = /login.html

    [plugin:auth_tkt]
    # identification and authentication
    use = repoze.who.plugins.auth_tkt:make_plugin
    secret = s33kr1t
    cookie_name = oatmeal
    secure = False
    include_ip = False
    digest_algo = sha512

    [plugin:basicauth]
    # identification and challenge
    use = repoze.who.plugins.basicauth:make_plugin
    realm = 'sample'

    [plugin:htpasswd]
    # authentication
    use = repoze.who.plugins.htpasswd:make_plugin
    filename = %(here)s/passwd
    check_fn = repoze.who.plugins.htpasswd:crypt_check

    [plugin:sqlusers]
    # authentication
    use = repoze.who.plugins.sql:make_authenticator_plugin
    # 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
    # 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

    [general]
    request_classifier = repoze.who.classifiers:default_request_classifier
    challenge_decider = repoze.who.classifiers:default_challenge_decider
    remote_user_key = REMOTE_USER

    [identifiers]
    # plugin_name;classifier_name:.. or just plugin_name (good for any)
    plugins =
          auth_tkt
          basicauth

    [authenticators]
    # plugin_name;classifier_name.. or just plugin_name (good for any)
    plugins =
          auth_tkt
          htpasswd
          sqlusers

    [challengers]
    # plugin_name;classifier_name:.. or just plugin_name (good for any)
    plugins =
          redirector;browser
          basicauth

    [mdproviders]
    plugins =
          sqlproperties

The basicauth section configures a plugin that does identification and
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
"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 auth_tkt cookie
identifier (unconditionally), then the basic auth plugin
(unconditionally).

The authenticators section provides an ordered list of plugins that
provide authenticator capability.  These will be consulted in the
defined order, so the system will look for users in the file, then in
the sql database when attempting to validate credentials.  No
classification prefixes are given to restrict which of the two plugins
are used, so both plugins are consulted regardless of the
classification of the request.  Each authenticator is called with each
set of identities found by the identifier plugins.  The first identity
that can be authenticated is used to set ``REMOTE_USER``.

The mdproviders section provides an ordered list of plugins that
provide metadata provider capability.  These will be consulted in the
defined order.  Each will have a chance (on ingress) to provide add
metadata to the authenticated identity.  Our example mdproviders
section shows one plugin configured: "sqlproperties".  The
sqlproperties plugin will add information related to user properties
(e.g. first name and last name) to the identity dictionary.

The challengers section provides an ordered list of plugins that
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 redirector challenger
will fire if it's a browser request, and the basic auth challenger
will fire if it's not (fallback).