### Navigation

- index
- modules |
- next |
- previous |
- repoze.what 1.0.9 documentation »
- The `repoze.what` Manual »

# Getting started with `repoze.what`

Overview

This document describes the basics of `repoze.what`, including its terminology and how to configure authentication and authorization easily.

## Terminology

As explained previously, `repoze.what`‘s base authorization pattern is based on the groups to which the user belongs and the permissions granted to such groups, and such groups and permissions can be stored in different types of sources – because of that, `repoze.what` uses a generic terminology when it deals with those sources:

source
  Where authorization data (groups and/or permissions) is stored. It may be a database or a file (an Htgroups file, an Ini file, etc), for example.
group source
  A source that stores groups. For example, an Htgroups file or an Ini file.
permission source
  A source that stores permissions. For example, an Ini file.
source adapter
  An object that manages a given type of source to add, edit and delete entries under an API independent of the source type.
group adapter
  An adapter that deals with one group source.
permission adapter
  An adapter that deals with one permission source.
section
  Sections are the compound elements that make up a source – this is, in a permission source, the sections are the permissions, and in a group source, the sections are the groups.
item
  The elements that are contained in a section. In a permission source, the items are the groups that are granted the permission represented in their parent section; likewise, in a group source, the items are the Ids of the users that belong to the group represented in the parent section.

The authentication framework (`repoze.who`) only deals with the sources that handle your users’ credentials, while the authorization framework (`repoze.what`) deals with both the sources that handle your groups and those that handle your permissions.

### Sample sources

Below are the contents of a mock `.htgroups` file that defines the groups of an application. In other words, such a file is a group source of type `htgroups`:

    developers: rms, linus, guido
    admins: rms, linus
    users: gustavo, maribel

It has three sections and five items: “developers” (made up of the items “rms”, “linus” and “guido”), “admins” (made up of the items “rms” and “linus”) and “users (made up of the items “gustavo” and “maribel”).

And below are the contents of a mock `.ini` file that defines the permissions of the groups in an application. In other words, such a file is a permission source of type `Ini`:

    [manage-site]
    admins
    [release-software]
    admins
    developers
    [contact-us]
    users

It has three sections and three items: “manage-site” (made up one item, “admins”), “release-software” (made up of the items “admins” and “developers”) and “contact-us” (made up of the item “users”).

If you use a database to store your users, groups and permissions, then such a database is both the group and permission source:

> - The tables where you store your groups and users are the sections and the section items, respectively, of the `group source`.
> - The tables where you store your permissions and groups are the sections and the section items, respectively, of the `permission source`.

## Setting up authentication and authorization

Note

If you are using a web framework and it already configures `repoze.what`, you may want to skip this section.

To enable authorization in your Web application, you need to add some WSGI middleware to your application, which is automatically done for you if you are using the `quickstart`.

When you enable authorization with `repoze.what`, authentication with `repoze.who` is automatically enabled.

Warning

Do not try to configure `repoze.who` directly – if you want authorization to work, you have to configure it through `repoze.what`.

### Using authentication and authorization without the quickstart

If you’re not using the quickstart, then you have to add the required middleware in your application. This gives you more flexibility, such as being able not to use a database to store your users’ credentials, your groups and/or your permissions.

You are highly encouraged to add such a middleware with a function defined in, say, `{yourproject}.config.middleware` and called, say, `add_auth`. Then that function may look like this:

    def add_auth(app):
        """
        Add authentication and authorization middleware to the ``app``.

        :param app: The WSGI application.
        :return: The same WSGI application, with authentication and
            authorization middleware.

        People will login using HTTP Authentication and their credentials are
        kept in an ``Htpasswd`` file. For authorization through repoze.what,
        we load our groups stored in an ``Htgroups`` file and our permissions
        stored in an ``.ini`` file.

        """

        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.ini import INIPermissionsAdapter
        # Please note that the Htgroups plugins has not been created yet; want
        # to jump in?
        from repoze.what.plugins.htgroups import HtgroupsAdapter

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

        # Defining the permission adapters; you may add as much as you need:
        permissions = {'all_perms': INIPermissionsAdapter('/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)
        return app_with_auth

Of course, there are other things you may customize, such as adding `repoze.who` identifiers, more authenticators, challengers and metadata providers (read `repoze.what.middleware.setup_auth()` for more information).

## What’s next?

Now you are ready to control authorization in your application with `predicates`!

### Navigation

- index
- modules |
- next |
- previous |
- repoze.what 1.0.9 documentation »
- The `repoze.what` Manual »