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
– aCharField
orEmailField
holding the user’s email address.password
– aCharField
holding the user’s password.is_active
– aBooleanField
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
– aDateField
orDateTimeField
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.