repoze.whoplugins.zodb 0.7

-----------------------
repoze.who.plugins.zodb
-----------------------

A repoze.who plugin to authenticate a userid and attach group
information based on information stored in a ZODB database.

Using a who config file:

.. code-block::
:linenos:

[plugin:zodb]
use = repoze.who.plugins.zodb:make_plugin
zodb_uri = zeo://localhost:8884/ # see repoze.zodbconn
users_finder = repoze.who.plugins.zodb:default_users_finder

[authenticators]
plugins = zodb

[mdproviders]
plugins = zodb

Using without a who config file:

..code-block::
:linenos:

from repoze.who.plugins.zodb import ZODBPlugin
from repoze.who.plugins.zodb import default_users_finder
plugin = ZODBPlugin('zeo://localhost:8884/', default_users_finder)
... then use plugin in a imperatively-configured repoze.who middleware setup..

ZODB URI
--------

See the documentation for ``repoze.zodbconn`` (a dependent package) to
understand the ``zodb_uri`` parameter.

The ZODB URI will be ignored if the connection is provided in the WSGI
environment by a WSGI component such as ``repoze.zodbconn#connector``.

Users Finder
------------

The "users finder" must be a function that accepts the root object of
a ZODB database and returns an object that implements
``repoze.who.plugins.zodb.interfaces.IUsers``. The default
implementation (``default_users_finder``) creates and stores the
implementation directly in the root itself under the key "users".

Authenticator and Metadata Provider
-----------------------------------

The authenticator will authenticate the user's credentials against the
information stored in the ``IUsers`` object.

The metadata provider will attach group information to the identity
(in the ``groups``) key based on information stored in the ``IUsers``
object.

Impersonation Plugin
--------------------

This package provides a repoze.who plugin that allows superusers to log
in as other users for testing purposes, without knowing the other
users' passwords. The impersonation plugin operates in tandem with a
normal ZODB authentication plugin.

Once the impersonation plugin is installed, users with superuser
privileges can use a special convention on the login form. Enter the
name of the user to impersonate in the login field, then enter the
superuser's name and password, separated by a colon, in the password
field. For example, if superuser ``alice`` wants to log in as ``bob``
without knowing his password, and alice's password is ``123``, then
Alice can enter ``bob`` for the login field and ``alice:123`` for the
password field. The system will authenticate Alice as ``bob``.

Using a who config file:

.. code-block::
:linenos:

[plugin:zodb]
use = repoze.who.plugins.zodb:make_plugin
zodb_uri = zeo://localhost:8884/ # see repoze.zodbconn
users_finder = repoze.who.plugins.zodb:default_users_finder

[plugin:zodb_impersonate]
use = repoze.who.plugins.zodb.impersonate:make_plugin
plugin_name = zodb
super_group = group.Superusers

[authenticators]
plugins = zodb
zodb_impersonate

[mdproviders]
plugins = zodb

The required ``plugin_name`` parameter specifies a ZODB plugin to use
to authenticate superusers and confirm their membership in the
superuser group. The required ``super_group`` parameter specifies which
group users must belong to in order to allow impersonation.

Both the ZODB plugin and the impersonation plugin should be configured
as authenticators. The impersonation plugin only attempts to authenticate
impersonation requests; it does not authenticate normal access.