Authentication and identification¶

state:	beta
dependencies:	Doqu, repoze.who

This bundle integrates Tool with repoze.who, a powerful and extremely configurable identification and authentication framework.

The extension provides:

sensible default configuration presets;
authenticator and metadata provider that let you store user accounts as Doqu documents;
automatic registration of the middleware in tool.application.ApplicationManager;
a protective decorator for views (requires_auth()) that ensures that the view is only available for authenticated users;
an easy way to access the user account document from any place of your application (the get_user() function).

You can choose between two commonly used configuration presets. You can also safely ignore both and configure repoze.who as desired (see custom_config).

Bundle configuration:

secret is a random string that is used to sign certain auth methods.
preset — name of the preset to use (see list of available presets below). Ignored if config if specified.
config — dotted path to a dictionary (or a callable that returns the dictionary) with custom configuration for the PluggableAuthenticationMiddleware. Note that the callable configurator will be called the bundle configuration dictionary.

Available presets:

“basic” — sets up Basic Access Authentication (RFC 2617).
“form” — sets up the “auth ticket” protocol and a HTTP form for identification, authentication and challenge.

Configuration examples¶

Basic authentication preset (in YAML, unrelated settings omitted):

tool.ext.who:
    preset: 'basic'

This is enough for basic authentication to work. Note that the credentials are compared against User instances, so make sure you have at least one user in the database. You can create one in the shell:

$ ./manage.py shell
>>> from tool.ext.who import User
>>> user = User(username='john')
>>> user.set_password('my cool password')  # will be encrypted
>>> user.save(context.docu_db)

Here we go, the user can now log in and his account object will be available via get_user(). You can also try the “form” preset for better integration with website design.

However, the presets are obviously useless for certain cases. You can always fine-tune the repoze.who middleware as if you would do without Tool.

An example of custom PluggableAuthenticationMiddleware configuration:

tool.ext.who:
    config: 'myproject.configs.who'

Here it is supposed that your custom configuration is composed according to the repoze.who middleware documentation (as keywords) and stored in the module myproject.configs like this:

who = {
    'identifiers': [('basic_auth', basic_auth)],
    …
}

API reference¶

tool.ext.who.requires_auth(view)¶: Decorator. Ensures that given view is only accessible bu authenticated users. If user is not authenticated, (s)he is asked for credentials according to the configuration (e.g. using one of presets).

tool.ext.who.get_user(request=None)¶

Returns a User instance associated with current user. If the user is not logged in, returns None.

This information is available through any request object but buried deep inside of it. The document instance is provided by DocuPlugin. Make sure it is loaded if you are using a custom configuration instead of presets.

Usage:

def some_view(request):
    user = get_user(request)

The request object is optional:

user = get_user()

If you only need the User document’s primary key, there’s a more straightforward way:

def some_view(request):
    user_id = request.remote_user

class tool.ext.who.User(**kw)¶: Represents a user. You can extend this class in whatever way you need, just keep in mind that User.set_password() and User.check_password() are essential for correct authentication.

tool v0.5.0 documentation