User on Renne Rocha

Extending built-in Django User with a custom Model

blog@rocha.dev.br (Renne Rocha) — Mon, 01 May 2023 19:28:40 -0300

The user authentication system provided by Django is extremely powerful and handles most of the authentication (Am I who I say I am?) and authorization (Am I authorized to do what I want to do?) needs of an web project. User accounts, groups and permissions, methods for handling passwords securely are part of this system.

Generally, this is adequate for most projects; however, there are situations where it becomes necessary to modify the behavior of a User or alter how their data is stored in the database. It should be noted that modifying the authorization and/or authentication process of a User will not be covered in this post.

Creating a user profile model is one solution to extend and modify the behavior of a User, as discussed before, but that approach has some caveats that are solved with the use of a custom user model.

Custom User model

We can tell Django which is the model that will replace the built-in django.contrib.auth.models.User model in the system. This is done by providing a value to AUTH_USER_MODEL in your project.

1
2

# myproject/myproject/settings.py
AUTH_USER_MODEL = "users.CustomUser"

Usually I create a users application to group all custom user related code to keep everything in the same context

It is highly recommended that you do this configuration at the beginning of the project, as after you have created your database tables, it will require you to fix your schema, moving data between tables and reapplying some migrations manually (see #25313 for an overview of the steps involved).

Now we need to create our custom model.

This new user model can handle different authentication and authorization schemes, can use different fields (e.g. email) to identify the user or any other requirement that is not satisfied using the default Django user model.

Adding new fields to default User model

If the default User model has everything we need and we want to add some extra profile fields keeping authentication and authorization as it is, create a custom model inheriting from AbstractUser would be enough.

# myproject/users/models.py
from django.contrib.auth.models import AbstractUser

class CustomUser(AbstractUser):
    date_of_birth = models.DateField(null=True)

1
2

# myproject/myproject/settings.py
AUTH_USER_MODEL = "users.CustomUser"

As we will not create a new table to store the user related information, there is no need for additional database queries to retrieve related models. We also don’t need to worry if a related model is created or not reducing the complexity of the system.

AbstractBaseUser

If we want to use a different field as the identifier (other than email), use a different authorization system and/or having more control on what fields we have in our user model, a custom model inheriting from AbstractBaseUser is the choice.

AbstractBaseUser is the core implementation of a User. It has a password field and methods to store and validate it securely. A last_login datetime field and everything else is up to us to provide.

If using the default authentication backend, our model must have a single unique field that will be the identifier of our user such as email address, username or any other unique attribute.

You configure that attribute using USERNAME_FIELD that defines what is the field that will uniquely identify the user.

EMAIL_FIELD

REQUIRED_FIELDS

is_active is an attribute on AbstractBaseUser defaulting to True

As an example, we will define a custom user that will use the email address as the identifier, has the date of birth as one required field can store the phone number and has a flag field in the database to indicate if the user is active or not.

# myproject/users/models.py
from django.contrib.auth.models import AbstractBaseUser

class CustomUser(AbstractBaseUser):
    USERNAME_FIELD = "email"
    EMAIL_FIELD = "email"
    REQUIRED_FIELDS = ["date_of_birth", ]

    date_of_birth = models.EmailField(unique=True)
    email = models.EmailField(unique=True)
    is_active = models.BooleanField(default=True)
    phone_number = models.CharField(max_length=16, blank=True)

FROM DOCS Authentication backends provide an extensible system for when a username and password stored with the user model need to be authenticated against a different service than Django’s default.

TODO: list all fields that are created with this

Any other fields needs to be created.

is_active is a property set to True, but you can define if you want

USERNAME_FIELD is needed identifier unique = True EMAIL_FIELD to specifi what is the email field REQUIRED_FIELDS fields required when createsuperuser

If we want to use email as the identifier of an user, we need to set USERNAME_FIELD property

# myproject/users/models.py
class CustomUser(AbstractBaseUser):
    USERNAME_FIELD = "email"

    email = models.EmailField()

One drawback is you need to specify a Custom Manager implementing two methods: create_user and create_superuser. This is required so we willll be able to run python manage.py createsuperuser and python manage.py create-user.

If some fields (TODO list what fields) from ABstractUser are there, you can use the built-in UserManager FROM DOCS username, email, is_staff, is_active, is_superuser, last_login, and date_joined fields the same as Django’s default user, you can install Django’s UserManager

# myproject/users/models.py
class CustomUser(AbstractBaseUser):
    USERNAME_FILED = "email"

    email = models.EmailField()

    objects = UserManager()

If you don’t want to use Django Admin (very unlikely), you’re done, and you can create/manage your users and authentication backend will be able.

However, if you want to use this custom user model with Django admin, there are some extra steps.

We need some fields and methods: is_staff so you have access to django admin is_active inactive users can’t access django admin

to manage permissions to edit registered models has_perm has_module_perms() we don’t need to use the built-in permission system (see PermissionMixin)

And UserCreationForm< UserChangeForm and PasswordResetForm (if we don’t have email field) needs to be customized so we can use that.

Also we need a custom UserAdmin to use our custom forms.

This is a lot of things, and sometimes difficult to remember. The docs are ok to describe the process, but IMO this should be much simpler :-P

If by any chance you want to use django model permission, you can use PermissionMixin, so you have access to groups, etc (to be honest, I never saw anything using permission, but groups)

Sometimes the username may not be the way you want to identify an user (an email or social number would be more suitable for your project) or we have different requirements for authorization and permission. In those cases creating a custom user model is a option.

This has advatanges over the user of a user profile model and solve some of the caveats of that approach such as:

We won’t need an extra database table to store your custom fields, so there is no performance problems to access them;
As the table that we store the User data required for Django authentication is the same, we don’t need to bother if your profile fields will be available or not

When creating a custom user model, we have two different options If you are going to this path, you can create your custom user inheriting from two different classes:

If using Django Admin, we also need to register this new model.

# myproject/users/admin.py
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from .models import CustomUser

admin.site.register(CustomUser, UserAdmin)

Extending built-in Django User with a Profile Model

blog@rocha.dev.br (Renne Rocha) — Mon, 24 Apr 2023 19:28:40 -0300

For the people that prefers video content you can also watch me explaining the content of this post in the following video (but in Portuguese):

Extending with an extra Model

The simplest way to extend your User is to create a new model with a OneToOneField relation to the default User model. This model will contain all extra fields that extends your User.

If we are satisfied by the default of Django User model and just want to add extra fields (like a user profile), this is the easiest and simpler solution.

As an example, to create a user profile storing the date of birth and phone number of a User we could use the model:

# myproject/userprofile/models.py
from django.db import models

class Profile(models.Model):
    user = models.OneToOneField(
        "auth.User", on_delete=models.CASCADE, related_name="profile"
    )
    date_of_birth = models.DateField(null=True)
    phone_number = models.CharField(max_length=32, blank=True)

    def __str__(self):
        return f"Profile of '{self.user.username}'"

However there are some caveats with this approach that we need to keep in mind to avoid unexpected issues such as:

A new table is created, so retrieving data from both tables will require more queries;
- The use of the select_related function can resolve performance issues caused by the new table. However, if we overlook this aspect, we may encounter unforeseen problems;
A Profile instance is not created automatically when you create a new User. We can solve this with a post_save signal handler;
- When multiple users are created simultaneously using the bulk_create method, post_save is not triggered, which may result in users being created without a Profile.
We need to do some extra work if we want to have these fields added to the User details in Django Admin

To create a new Profile when a new User is created we need to catch post_save signal:

# myproject/userprofile/signals.py
from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User

from userprofile.models import Profile

@receiver(post_save, sender=User)
def create_user_profile(sender, instance, created, *args, **kwargs):
    # Ensure that we are creating an user instance, not updating it
    if created:
        Profile.objects.create(user=instance)

# myproject/userprofile/apps.py
from django.apps import AppConfig

class UserprofileConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "userprofile"

    def ready(self):
        # Register your signal here, so it will be imported once
        # when the app is ready
        from userprofile import signals  # noqa

Running the application, we will ensure that every time we create a new User, a related Profile will be created as well:

In [1]: from django.contrib.auth.models import User
   ...: from userprofile.models import Profile

In [2]: Profile.objects.all()
Out[2]: <QuerySet []>

In [3]: user = User.objects.create(username="myuser", email="email@myuser.com")

In [4]: Profile.objects.all()
Out[4]: <QuerySet [<Profile: Profile of 'myuser'>]>

As mentioned before, when creating instances in bulk, the signal will not be emited, so the Profile will not be automatically created:

In [5]: users = User.objects.bulk_create(
   ...:     [
   ...:         User(username="First user", email="user1@user1.com"),
   ...:         User(username="Second user", email="user2@user2.com"),
   ...:     ]
   ...: )

In [6]: users
Out[6]: [<User: First user>, <User: Second user>]

In [7]: Profile.objects.all()
Out[7]: <QuerySet [<Profile: Profile of 'myuser'>]>

One limitation of this approach is that we are not allowed to have required fields in the user profile without providing a default value.

As an example, if we require that date_of_birth is mandatory and our Profile model is like the following:

# myproject/userprofile/models.py
from django.db import models

class Profile(models.Model):
    user = models.OneToOneField(
        "auth.User", on_delete=models.CASCADE, related_name="profile"
    )
    date_of_birth = models.DateField()  # date_of_birth IS REQUIRED
    phone_number = models.CharField(max_length=32, blank=True)

    def __str__(self):
        return f"Profile of '{self.user.username}'"

When creating a new user, our post_save handler will fail:

In [1]: from django.contrib.auth.models import User
   ...: from userprofile.models import Profile

In [2]: user = User.objects.create(username="myuser", email="email@myuser.com")
---------------------------------------------------------------------------
IntegrityError                            Traceback (most recent call last)
(...)
IntegrityError: NOT NULL constraint failed: userprofile_profile.date_of_birth

Keeping in mind these caveats, extending the User model through this method is a simple and efficient solution that can meet the needs of many web applications.