Django Custom User Model

Will Vincent - Feb 5 '20 - - Dev Community

Django ships with a built-in User model for authentication, however the official Django documentation highly recommends using a custom user model for new projects. The reason is if you want to make any changes to the User model down the road--for example adding a date of birth field--using a custom user model from the beginning makes this quite easy. But if you do not, updating the default User model in an existing Django project is very, very challenging.

So always use a custom user model for all new Django projects. However the official documentation example is not actually what many Django experts recommend using. There is a far easier yet still powerful approach to starting off new Django projects with a custom user model which I'll demonstrate here.

If you're brand new to user authentication in Django, I recommend first reviewing how to implement a regular login, logout, signup flow in Django which covers the basics in detail.

Setup

To start, create a new Django project from the command line. We need to do several things:

  • create and navigate into a dedicated directory called users for our code
  • install Django
  • make a new Django project called config
  • make a new app users
  • start the local web server

Here are the commands to run:

$ cd ~/Desktop
$ mkdir users && cd users
$ pipenv install django==3.0.3
$ pipenv shell
(users) $ django-admin.py startproject config .
(users) $ python manage.py startapp users
(users) $ python manage.py runserver
Enter fullscreen mode Exit fullscreen mode

Note that we did not run migrate to configure our database. It's important to wait until after we've created our new custom user model before doing so.

If you navigate to http://127.0.0.1:8000 you’ll see the Django welcome screen.

Django welcome page

AbstractUser vs AbstractBaseUser

There are two modern ways to create a custom user model in Django: AbstractUser and AbstractBaseUser. In both cases we can subclass them to extend existing functionality however AbstractBaseUser requires much, much more work. Seriously, don't mess with it unless you really know what you're doing. And if you did, you wouldn't be reading this tutorial, would you?

So we'll use AbstractUser which actually subclasses AbstractBaseUser but provides more default configuration.

Custom User Model

Creating our initial custom user model requires four steps:

  • update settings.py
  • create a new CustomUser model
  • create new UserCreation and UserChangeForm
  • update the admin

In settings.py we'll add the users app and use the AUTH_USER_MODEL config to tell Django to use our new custom user model in place of the built-in User model. We'll call our custom user model CustomUser.

Within INSTALLED_APPS add users.apps.UsersConfig at the bottom. Then at the bottom of the entire file, add the AUTH_USER_MODEL config.

# config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'users.apps.UsersConfig', # new
]
...
AUTH_USER_MODEL = 'users.CustomUser' # new
Enter fullscreen mode Exit fullscreen mode

Now update models.py with a new User model which we'll call CustomUser.

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

class CustomUser(AbstractUser):
    pass
    # add additional fields in here

    def __str__(self):
        return self.username
Enter fullscreen mode Exit fullscreen mode

We need new versions of two form methods that receive heavy use working with users. Stop the local server with Control+c and create a new file in the users app called forms.py.

(users) $ touch users/forms.py
Enter fullscreen mode Exit fullscreen mode

We'll update it with the following code to largely subclass the existing forms.

# users/forms.py
from django import forms
from django.contrib.auth.forms import UserCreationForm, UserChangeForm
from .models import CustomUser

class CustomUserCreationForm(UserCreationForm):

    class Meta:
        model = CustomUser
        fields = ('username', 'email')

class CustomUserChangeForm(UserChangeForm):

    class Meta:
        model = CustomUser
        fields = ('username', 'email')
Enter fullscreen mode Exit fullscreen mode

Finally we update admin.py since the Admin is highly coupled to the default User model.

# users/admin.py
from django.contrib import admin
from django.contrib.auth import get_user_model
from django.contrib.auth.admin import UserAdmin

from .forms import CustomUserCreationForm, CustomUserChangeForm
from .models import CustomUser

class CustomUserAdmin(UserAdmin):
    add_form = CustomUserCreationForm
    form = CustomUserChangeForm
    model = CustomUser
    list_display = ['email', 'username',]

admin.site.register(CustomUser, CustomUserAdmin)
Enter fullscreen mode Exit fullscreen mode

And we're done! We can now run makemigrations and migrate for the first time to create a new database that uses the custom user model.

(users) $ python manage.py makemigrations users
(users) $ python manage.py migrate
Enter fullscreen mode Exit fullscreen mode

Superuser

It's helpful to create a superuser that we can use to login to the admin and test out login/logout. On the command line type the following command and go through the prompts.

(users) $ python manage.py createsuperuser
Enter fullscreen mode Exit fullscreen mode

Templates/Views/URLs

Our goal is a homepage with links to login, logout, and signup. Start by updating settings.py to use a project-level templates directory.

# config/settings.py
TEMPLATES = [
    {
        ...
        'DIRS': [os.path.join(BASE_DIR, 'templates')], # new
        ...
    },
]
Enter fullscreen mode Exit fullscreen mode

Then set the redirect links for login and logout, which will both go to our home template. Add these two lines at the bottom of the file.

# config/settings.py
LOGIN_REDIRECT_URL = 'home'
LOGOUT_REDIRECT_URL = 'home'
Enter fullscreen mode Exit fullscreen mode

Create a new project-level templates folder and within it a registration folder as that's where Django will look for the login template.

(users) $ mkdir templates
(users) $ mkdir templates/registration
Enter fullscreen mode Exit fullscreen mode

Then create four templates:

(users) $ touch templates/registration/login.html
(users) $ touch templates/base.html
(users) $ touch templates/home.html
(users) $ touch templates/signup.html
Enter fullscreen mode Exit fullscreen mode

Update the files as follows:

<!-- templates/base.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{% block title %}Django Auth Tutorial{% endblock %}</title>
</head>
<body>
  <main>
    {% block content %}
    {% endblock %}
  </main>
</body>
</html>
Enter fullscreen mode Exit fullscreen mode 
<!-- templates/home.html -->
{% extends 'base.html' %}

{% block title %}Home{% endblock %}

{% block content %}
{% if user.is_authenticated %}
  Hi {{ user.username }}!
  <p><a href="{% url 'logout' %}">logout</a></p>
{% else %}
  <p>You are not logged in</p>
  <a href="{% url 'login' %}">login</a> |
  <a href="{% url 'signup' %}">signup</a>
{% endif %}
{% endblock %}
Enter fullscreen mode Exit fullscreen mode 
<!-- templates/registration/login.html -->
{% extends 'base.html' %}

{% block title %}Login{% endblock %}

{% block content %}
<h2>Login</h2>
<form method="post">
  {% csrf_token %}
  {{ form.as_p }}
  <button type="submit">Login</button>
</form>
{% endblock %}
Enter fullscreen mode Exit fullscreen mode 
<!-- templates/signup.html -->
{% extends 'base.html' %}

{% block title %}Sign Up{% endblock %}

{% block content %}
<h2>Sign up</h2>
<form method="post">
  {% csrf_token %}
  {{ form.as_p }}
  <button type="submit">Sign up</button>
</form>
{% endblock %}
Enter fullscreen mode Exit fullscreen mode

Now for our urls.py files at the project and app level.

# config/urls.py
from django.contrib import admin
from django.urls import path, include
from django.views.generic.base import TemplateView

urlpatterns = [
    path('', TemplateView.as_view(template_name='home.html'), name='home'),
    path('admin/', admin.site.urls),
    path('users/', include('users.urls')),
    path('users/', include('django.contrib.auth.urls')),
]
Enter fullscreen mode Exit fullscreen mode

Create a urls.py file in the users app.

(users) $ touch users/urls.py
Enter fullscreen mode Exit fullscreen mode

Then fill in the following code:

# users/urls.py
from django.urls import path
from .views import SignUpView

urlpatterns = [
    path('signup/', SignUpView.as_view(), name='signup'),
]
Enter fullscreen mode Exit fullscreen mode

Last step is our views.py file in the users app which will contain our signup form.

# users/views.py
from django.urls import reverse_lazy
from django.views.generic.edit import CreateView

from .forms import CustomUserCreationForm

class SignUpView(CreateView):
    form_class = CustomUserCreationForm
    success_url = reverse_lazy('login')
    template_name = 'signup.html'
Enter fullscreen mode Exit fullscreen mode

Ok, phew! We're done. Let's test it out.

Start up the server with python manage.py runserver and go to the homepage at http://127.0.0.1:8000/.

Home page

Click on login and use your superuser credentials.

Login page

Upon successful submission you'll be redirected back to the homepage and see a personalized greeting.

Homepage with superuser

Now use the logout link and then click on signup.

Signup page

Create a new user. Mine is called testuser. After successfully submitting the form you'll be redirected to the login page. Login with your new user and you'll again be redirected to the homepage with a personalized greeting for the new user.

Homepage with new user

If you want to peruse the admin log into it with your superuser account at http://127.0.0.1:8000/admin. If you look at Users you can see our two users.

Users in the Admin

Conclusion

Now that our custom user model is configured you can easily and at any time add additional fields to it. See the Django docs for further instructions.

You can also check out DjangoX, which is an open-source Django starter framework that includes a custom user model, email/password by default instead of username/email/password, social authentication, and more.

Image
Exploring the Metaverse and the Future of Virtual Reality (VR)
Image
Phonepe wrong transaction

webdev, javascript, beginners, programming
Image
Phonepe wrong transaction

webdev, javascript, beginners, programming
Image
How Decentralized Apps Can Make Everyday Tasks Easy

opensource, web5, decentralization, community
Image
Understanding RESTful API and Web Services: Key Differences and Use Cases

restapi, webdev, javascript, beginners
Image
Bandar Judi Online Sah Serta Penyiapan Yang Benar Buat Register
Image
Modern IT Technologies: Transforming the Digital Landscape

web3
Image
Uncovering developer discontent: Why are so many software engineers unhappy?

softwaredevelopment, softwareengineering, management, developers
Image
Situs Judi Online Terunggul Dengan Bonus Yang Menjanjikan
Image
Situs Judi Online Terunggul Dengan Payment Amat Gampang Serta Terjaga
Image
Consistency with React

react, ui, ux
Image
How to Write Clear and Effective Code Comments in JavaScript with Better Comments

javascript, coding, productivity, webdev
Image
API Debugging: Best Practices for Fetching Test Data from a Database

nextjs, api, testing, java
Image
Looking for an Oracle Database Developer for Remote Work (Ukraine-Based)
Image
Welcome to my page!❤️🙌
Image
Agile + DevOpsDays Des Moines 2024: Finding A Common Path With Empathy, Automation, And Security

security, cybersecurity, devops, developers
Image
How to Build a Weather App in VSCode for Beginners(1): Backend Design& API Testing

vscode, apitesting, beginners, react
Image
From Monolith to Monorepo: A Next.js Migration Story

typescript, javascript, nextjs, turborepo
Image
Trik Main Judi Online Supaya Tidak Kolaps serta Rugi Selalu
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .