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 RegistrationView, ActivationView, and 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. The two-step 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 HMAC-based) 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 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 RegistrationProfile model, which does make the above-noted assumptions about the structure of your user model.