The inner-workings of repoze.what

Overview

repoze.what doesn’t provide WSGI middleware per se. Instead, it configures and re-uses repoze.who‘s.

Middleware-related components are defined in the repoze.what.middleware module. It contains one function to configure repoze.who with support for repoze.what and the repoze.who metadata provider that loads authorization-related data in the repoze.who identity and the repoze.what credentials dictionaries.

Warning

In repoze.what v2, the userid, groups and permissions will only be loaded in the repoze.what credentials dictionary (environ['repoze.what.credentials']). So you are encouraged not to access this data from the repoze.who identity – if you do so, you will have to update your code when you want to upgrade to v2.

repoze.what.middleware.setup_auth(app, group_adapters=None, permission_adapters=None, **who_args)

Setup repoze.who with repoze.what support.

Parameters:
  • app – The WSGI application object.
  • group_adapters (dict) – The group source adapters to be used.
  • permission_adapters (dict) – The permission source adapters to be used.
  • who_args – Authentication-related keyword arguments to be passed to repoze.who.
Returns:

The WSGI application with authentication and authorization middleware.

Tip

If you are looking for an easier way to get started, you may want to use the quickstart plugin and its setup_sql_auth() function.

You must define the group_adapters and permission_adapters keyword arguments if you want to use the groups/permissions-based authorization pattern.

Additional keyword arguments will be passed to repoze.who.plugins.testutil.make_middleware() – and among those keyword arguments, you must define at least the identifier(s), authenticator(s) and challenger(s) to be used. For example:

from repoze.who.plugins.basicauth import BasicAuthPlugin
from repoze.who.plugins.htpasswd import HTPasswdPlugin, crypt_check

from repoze.what.middleware import setup_auth
from repoze.what.plugins.xml import XMLGroupsAdapter
from repoze.what.plugins.ini import INIPermissionAdapter

# Defining the group adapters; you may add as much as you need:
groups = {'all_groups': XMLGroupsAdapter('/path/to/groups.xml')}

# Defining the permission adapters; you may add as much as you need:
permissions = {'all_perms': INIPermissionAdapter('/path/to/perms.ini')}

# repoze.who identifiers; you may add as much as you need:
basicauth = BasicAuthPlugin('Private web site')
identifiers = [('basicauth', basicauth)]

# repoze.who authenticators; you may add as much as you need:
htpasswd_auth = HTPasswdPlugin('/path/to/users.htpasswd', crypt_check)
authenticators = [('htpasswd', htpasswd_auth)]

# repoze.who challengers; you may add as much as you need:
challengers = [('basicauth', basicauth)]

app_with_auth = setup_auth(
    app,
    groups,
    permissions,
    identifiers=identifiers,
    authenticators=authenticators,
    challengers=challengers)

Attention

Keep in mind that repoze.who must be configured through repoze.what for authorization to work.

Note

If you want to skip authentication while testing your application, you should pass the skip_authentication keyword argument with a value that evaluates to True.

Changed in version 1.0.5: repoze.who.middleware.PluggableAuthenticationMiddleware replaced with repoze.who.plugins.testutil.make_middleware() internally.

WSGI environment variables

repoze.what defines and uses the following WSGI environment variables:

  • repoze.what.credentials: It contains authorization-related data about the current user (it’s similar to repoze.who‘s identity). It is a dictionary made up of the following items: userid (the user name of the current user, if not anonymous; copied from environ['repoze.who.identity']['repoze.who.userid'] in repoze.what v1.X), groups (tuple of groups to which the currrent user belongs) and permissions (tuple of permissions granted to such groups).

    Warning

    Do not access this dictionary directly, use a predicate checker instead. This variable is internal and the disposal or availability of its items may change at any time.

  • repoze.what.adapters: It contains the available source adapters, if any. It’s a dictionary made up of the following items: groups (dictionary of group adapters) and permissions (dictionary of permission adapters).

Warning

Because repoze.what 1.X works as a repoze.who metadata provider, the variables above are defined if and only if the current user is not anonymous. This limitation will not exist in repoze.what v2, since it will have its own middleware.