User registration backends

At its core, django-registration is built around the idea of pluggable backends which can implement different workflows for user registration. Although the default backend uses a common two-phase system (registration followed by activation), backends are generally free to implement any workflow desired by their authors.

This is deliberately meant to be complementary to Django’s own pluggable authentication backends; a site which uses an OpenID authentication backend, for example, can and should make use of a registration backend which handles signups via OpenID. And, like a Django authentication backend, a registration backend is simply a class which implements a particular standard API (described below).

This allows for a great deal of flexibility in the actual workflow of registration; backends can, for example, implement any of the following (not an exhaustive list):

• One-step (register, and done) or multi-step (register and activate) signup.
• Invitation-based registration.
• Selectively allowing or disallowing registration (e.g., by requiring particular credentials to register).
• Enabling/disabling registration entirely.
• Registering via sources other than a standard username/password, such as OpenID.
• Selective customization of the registration process (e.g., using different forms or imposing different requirements for different types of users).

Specifying the backend to use

To determine which backend to use, the views in django-registration accept a keyword argument backend; in all cases, this should be a string containing the full dotted Python import path to the backend class to be used. So, for example, to use the default backend, you’d pass the string 'registration.backends.default.DefaultBackend' as the value of the backend argument (and the default URLconf included with that backend does so). The specified backend class will then be imported and instantiated (by calling its constructor with no arguments), and the resulting instance will be used for all backend-specific functionality.

If the specified backend class cannot be imported, django-registration will raise django.core.exceptions.ImproperlyConfigured.

Backend API

To be used as a registration backend, a class must implement the following methods. For many cases, subclassing the default backend and selectively overriding behavior will be suitable, but for other situations (e.g., workflows significantly different from the default) a full implementation is needed.

register(request, **kwargs)

This method implements the logic of actually creating the new user account. Often, but not necessarily always, this will involve creating an instance of django.contrib.auth.models.User from the supplied data.

This method will only be called after a signup form has been displayed, and the data collected by the form has been properly validated.

Arguments to this method are:

request

The Django HttpRequest object in which a new user is attempting to register.

**kwargs

A dictionary of the cleaned_data from the signup form.

After creating the new user account, this method should create or obtain an instance of django.contrib.auth.models.User representing that account. It should then send the signal registration.signals.user_registered, with three arguments:

sender

The backend class (e.g., self.__class__).

user

The User instance representing the new account.

request

The HttpRequest in which the user registered.

Finally, this method should return the User instance.

activate(request, **kwargs)

For workflows which require a separate activation step, this method should implement the necessary logic for account activation.

Arguments to this method are:

request

The Django HttpRequest object in which the account is being activated.

**kwargs

A dictionary of any additional arguments (e.g., information captured from the URL, such as an activation key) received by the activate() view. The combination of the HttpRequest and this additional information must be sufficient to identify the account which will be activated.

If the account cannot be successfully activated (for example, in the default backend if the activation period has expired), this method should return False.

If the account is successfully activated, this method should create or obtain an instance of django.contrib.auth.models.User representing the activated account. It should then send the signal registration.signals.user_activated, with three arguments:

sender

The backend class.

user

The User instance representing the activated account.

request

The HttpRequest in which the user activated.

This method should then return the User instance.

For workflows which do not require a separate activation step, this method can and should raise NotImplementedError.

registration_allowed(request)

This method returns a boolean value indicating whether the given HttpRequest is permitted to register a new account (True if registration is permitted, False otherwise). It may determine this based on some aspect of the HttpRequest (e.g., the presence or absence of an invitation code in the URL), based on a setting (in the default backend, a setting can be used to disable registration), information in the database or any other information it can access.

Arguments to this method are:

request

The Django HttpRequest object in which a new user is attempting to register.

If this method returns False, the register() view will not display a form for account creation; instead, it will issue a redirect to a URL explaining that registration is not permitted.

get_form_class(request)

This method should return a form class – a subclass of django.forms.Form – suitable for use in registering users with this backend. As such, it should collect and validate any information required by the backend’s register method.

Arguments to this method are:

request

The Django HttpRequest object in which a new user is attempting to register.

post_registration_redirect(request, user)

This method should return a location to which the user will be redirected after successful registration. This should be a tuple of (to, args, kwargs), suitable for use as the arguments to Django’s “redirect” shortcut.

Arguments to this method are:

request

The Django HttpRequest object in which the user registered.

user

The User instance representing the new user account.

post_activation_redirect(request, user)

For workflows which require a separate activation step, this method should return a location to which the user will be redirected after successful activation. This should be a tuple of (to, args, kwargs), suitable for use as the arguments to Django’s “redirect” shortcut.

Arguments to this method are:

request

The Django HttpRequest object in which the user activated.

user

The User instance representing the activated user account.

For workflows which do not require a separate activation step, this method can and should raise NotImplementedError.