custom-user.rst

Custom user models

When django-registration was first developed, Django's authentication system supported only its own built-in user model, django.contrib.auth.models.User. More recent versions of Django have introduced support for custom user models.

It is possible to use django-registration with a custom user model, so long as certain factors are accounted for.

Warning

Using email address as username

If your custom user model treats the email address as a username, or otherwise does not have distinct email address and username fields, you must write a custom registration workflow including custom registration form; the built-in workflows of django-registration will not function with a user model which uses the email address as a username.

Writing a custom registration workflow

The most straightforward way to guarantee compatibility with a custom user model is simply to write your own custom registration workflow, subclassing :class:`~registration.views.RegistrationView`, :class:`~registration.views.ActivationView`, and :class:`~registration.forms.RegistrationForm` as necessary. Refer to the documentation for those classes for notes on how to customize them.

Using the built-in workflows

If you want to use one of the registration workflows built in to django-registration, there is some accommodation for custom user models. :ref:`The two-step model workflow <model-workflow>` uses a model with a OneToOneField to the user model, and uses the recommended practice of referring to it via the AUTH_USER_MODEL setting. All built-in workflows also avoid importing or directly referring to Django's default user model, instead using the get_user_model() helper provided in django.contrib.auth to obtain a reference to whatever model has been specified to represent users.

However, all of these workflows do make some assumptions about the structure of your user model.

The two-step workflows (both model-based and :ref:`HMAC-based <hmac-workflow>`) require that your user model define the following fields, which are found on Django's default user model:

• email -- a CharField or EmailField holding the user's email address. This field is required by :class:`~registration.forms.RegistrationForm`.
• password -- a CharField holding the user's password.
• is_active -- a BooleanField indicating whether the user's account is active.

You also must specify the attribute USERNAME_FIELD on your custom user model to denote the field used as the username, and that field must accept string values.

Additionally, the model-based workflow requires this field:

• date_joined -- a DateField or DateTimeField indicating when the user joined the site.

The model-based and HMAC workflows also require that the user model define a manager class named objects, and that this manager class provide a method create_user, which will create and return a user instance from the arguments USERNAME_FIELD (django-registration will use that to determine the name of the username field) email, and password, and require that the user model provide the email_user method on instances.

The simple one-step workflow requires USERNAME_FIELD to be specified (and for that field to accept strings), requires email and password fields, and requires the existence of an objects manager defining create_user, as in the two-step workflows.

If your custom user model cannot meet these API requirements, your only option for using django-registration will be to write your own registration workflow.

If you wish to write your own subclasses of the forms and views from the model-based workflow, but will be customizing them to an incompatible custom user model, also note that you must not add registration to your INSTALLED_APPS setting, as doing so would install the default workflow's :class:`~registration.models.RegistrationProfile` model, which does make the above-noted assumptions about the structure of your user model.