repoze.who – Authentication in TurboGears 2 applications

Status:Official Website:http://static.repoze.org/whodocs/

Overview

This document describes how repoze.who is integrated into TurboGears and how you make get started with it. For more information, you may want to check repoze.who’s website.

repoze.who is a powerful and extensible authentication package for arbitrary WSGI applications. Within TurboGears, it’s configured through repoze.what.

How it works

It’s a WSGI middleware which is able to authenticate the user through the method you want (e.g., LDAP or HTTP authentication), “remember” the user in future requests and log the user out.

You can customize the interaction with the user through four kinds of plugins, sorted by the order in which they are run on each request:

• An identifier plugin, with no action required on the user’s side, is able to tell whether it’s possible to authenticate the user (e.g., if it finds HTTP Authentication headers in the HTTP request). If so, it will extract the data required for the authentication (e.g., username and password, or a session cookie). There may be many identifiers and repoze.who will run each of them until one finds the required data to authenticate the user.
• If at least one of the identifiers could find data necessary to authenticate the current user, then an authenticator plugin will try to use the extracted data to authenticate the user. There may be many authenticators and repoze.who will run each of them until one authenticates the user.
• When the user tries to access a protected area or the login page, a challenger plugin will come up to request an action from the user (e.g., enter a user name and password and then submit the form). The user’s response will start another request on the application, which should be caught by an identifier to extract the login data and then such data will be used by the authenticator.
• For authenticated users, repoze.who provides the ability to load related data (e.g., real name, email) in the WSGI environment so that it can be easily used in the application. Such a functionality is provided by so-called metadata provider plugins. There may be many metadata providers and repoze.who will run them all.

When repoze.who needs to store data about the authenticated user in the WSGI environment, it uses its repoze.who.identity key, which can be accessed using the code below:

from tg import request

# The authenticated user's data kept by repoze.who:
identity = request.environ.get('repoze.who.identity')

Such a value is a dictionary and is often called “the identity dict”. It will only be defined if the current user has been authenticated.

Tip

There is a short-cut to the code above in the WSGI request, which will be defined in {yourproject}.lib.base.BaseController if you enabled authentication and authorization when you created the project.

For example, to check whether the user has been authenticated you may use:

   # ...
   from tg import request
   # ...
   if request.identity:
       flash('You are authenticated!')

``request.identity`` will equal to ``None`` if the user has not been
authenticated.

Likewise, this short-cut is also set in the template context as
``tg.identity``.

The username will be available in identity['repoze.who.userid'] (or request.identity['repoze.who.userid'], depending on the method you select).

How it works in TurboGears applications

TurboGears itself doesn’t deal directly with repoze.who. It’s configured through repoze.what because it has to configure repoze.who in a special way so that authorization can work.

By default, repoze.what in TurboGears 2.1.5 configures repoze.who to use its repoze.who.plugins.form.RedirectingFormPlugin as the first identifier and challenger – using /login as the relative URL that will display the login form, /login_handler as the relative URL where the form will be sent and /logout_handler as the relative URL where the user will be logged out. The so-called rememberer of such identifier will be an instance of repoze.who.plugins.cookie.AuthTktCookiePlugin. All these settings can be customized through repoze.what.plugins.quickstart.

You don’t have to use repoze.who directly either, unless you decide not to use it the way TurboGears configures it through repoze.what.

Advanced topics

If you’re looking for different authentication methods, you may want to visit the repoze.who website to check if the plugin you’re looking for is already available or how to create your own plugins. Then you should also check the repoze.what documentation to learn how to setup the new settings.