Step-by-Step Guide to User Authentication with Django, Djoser, and JWT: Part I

User authentication and management are foundational features when starting a new project. Because these tasks are often repeated, various packages have been developed to streamline the process, allowing developers to focus on other aspects of their projects. One such package is Djoser, which integrates seamlessly with Django REST Framework (DRF) to handle authentication and user management. In this guide, I’ll walk you through building a full user authentication system using Djoser, including setting up email functionality and custom email templates.

Setting Up the Project

Start by creating a directory for your project:

mkdir userauth

Navigate to the new directory in your preferred IDE, set up a virtual environment and activate it

python venv .venv
source .venv/bin/activate

Next, install the necessary packages:

pip install django djangorestframework djoser djangorestframework_simplejwt social-auth-app-django drf-yasg

Note: Some dependencies, such as social-auth-app-django, might be installed automatically with Djoser. If so, you can skip explicitly adding them

Once installed, generate a requirements.txt file to track your dependencies:

pip freeze > requirements.txt

You should see all the installed packages listed in the requirements.txt file, including any dependencies.

Create the Django Project and get the server running

django-admin startapp userauth . 

This will create the django project. We then need to create an app inside our project

python manage.py startapp accounts

Your project directory should now contain the following:

• .venv (virtual environment)

• accounts/ (authentication app)

• userauth/ (main project folder)

• manage.py

• requirements.txt

Configuring the Project

Add the required packages and apps to the INSTALLED_APPS section in settings.py:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

     # Third Party Apps
    'rest_framework',
    'djoser',
    'rest_framework_simplejwt',
    'drf_yasg',

    # Local Apps
    'accounts',
]

Update your settings.py to include configurations for Django REST Framework and SimpleJWT:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
}

Let's create our custom user model since
create managers.py file in the accounts folder
accounts/managers.py

from django.contrib.auth.models import BaseUserManager


class CustomUserManager(BaseUserManager):

    def create_user(self, email, username, password=None, **extra_fields) -> None:

        if not username:
            raise ValueError("Username is required")

        if not email:
            raise ValueError("Email is required")


        email = self.normalize_email(email)
        user = self.model(email=email, username=username, **extra_fields)
        user.set_password(password)
        user.save()
        return user


    def create_superuser(self, email, username, password, **extra_fields):
        """
        Create and save a SuperUser with the given email and password.
        """
        extra_fields.setdefault("is_staff", True)
        extra_fields.setdefault("is_superuser", True)
        extra_fields.setdefault("is_active", True)

        if extra_fields.get("is_staff") is not True:
            raise ValueError("Superuser must have is_staff=True.")

        if extra_fields.get("is_superuser") is not True:
            raise ValueError("Superuser must have is_superuser=True.")

        return self.create_user(email, username, password, **extra_fields)

accounts/models.py

from django.db import models
from django.contrib.auth.models import AbstractUser
from accounts.managers import CustomUserManager



class CustomUser(AbstractUser):
    username = None
    email = models.EmailField(unique=True)
    is_verified = models.BooleanField(default=False)


    USERNAME_FIELD = 'email'
    REQUIRED_FIELDS = []

    objects = CustomUserManager()


    def __str__(self):
        return self.email

Add this line in your settings.py file

AUTH_USER_MODEL = 'accounts.CustomUser'

We can go ahead to make our migrations then run the local development server

python manage.py makemigrations
python manage.py migrate
python manage.py runserver

There should be no issues up to this point.

Configuring Djoser URLs

Include the URLs that Djoser provides in your project’s URL patterns, along with Swagger for API documentation:

userauth/urls.py

from django.contrib import admin
from django.urls import include, path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi


schema_view = get_schema_view(
    openapi.Info(
        title="User Accounts API",
        default_version="v1",
        description="REST implementation of Django authentication system using Djoser",
        contact=openapi.Contact(email="[e-mail]"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/docs', schema_view.with_ui("swagger", cache_timeout=0), name="swagger-ui"),
    path('api/', include('djoser.urls')), 
    path('api/', include('djoser.urls.jwt'))
]

Go to http://127.0.0.1:8000/api/docs/ in your browser to view the API documentation.

Configuring Djoser Settings

All settings that can be configured for djoser can be found here Djoser settings

userauth/settings.py

DJOSER = {
    "LOGIN_FIELD": "email",
    "SEND_ACTIVATION_EMAIL": True,
    "ACTIVATION_URL": "accounts/activation/{uid}/{token}/",
    "SEND_CONFIRMATION_EMAIL": True,
}

Here we are requiring users to receive an activation email. The activation url is the link sent to the user's email for them to click. The token and uid needs to be extracted and a post request sent with them as the body to the activation route in your project

Configuring Email Sending

Finally we need to configure email sending. I'll be using mailtrap for email sending. You can choose to send the email to the console or whatever email service you choose.

For sending the email to your console

EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"

Using external mail service

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'sandbox.smtp.mailtrap.io'
EMAIL_PORT = '2525'
EMAIL_HOST_USER = 'email-username'
EMAIL_HOST_PASSWORD = 'email-password'

Replace the placeholders with the correct credentials

To test this out, we'll use postman to test it out.

Creating a new user

Then the activation email sent to the user

Customizing Email Templates

Let's customize the email template a little
Create a template folder in the accounts directory, then create an email folder and go ahead to create template folder in there

accounts/templates/email/activation_email.py
We customize the default email that comes with djoser

{% load i18n %}

{% block subject %}
{% blocktrans %}Account activation{% endblocktrans %}
{% endblock subject %}

{% block text_body %}
{% blocktrans %}You're receiving this email because you need to finish activation process on {{ site_name }}.{% endblocktrans %}

{% trans "Please go to the following page to activate your account:" %}
{{ protocol }}://{{ domain }}/{{ url|safe }}

{% trans "Thanks for using our site!" %}

{% blocktrans %}The {{ site_name }} team{% endblocktrans %}
{% endblock text_body %}

{% block html_body %}
<div style="font-family: Arial, sans-serif; background-color: #f9f9f9; padding: 20px;">
    <div style="max-width: 600px; margin: 0 auto; background-color: #ffffff; border: 1px solid #ddd; border-radius: 10px; overflow: hidden;">
        <div style="background-color: #4CAF50; color: white; padding: 20px; text-align: center;">
            <h1 style="margin: 0;">{{ site_name }}</h1>
        </div>
        <div style="padding: 20px;">
            <p style="font-size: 16px; color: #333;">
                {% blocktrans %}You're receiving this email because you need to finish the activation process on {{ site_name }}.{% endblocktrans %}
            </p>
            <p style="font-size: 16px; color: #333;">
                {% trans "Please go to the following page to activate your account:" %}
            </p>
            <p style="text-align: center; margin: 20px 0;">
                <a href="{{ protocol }}://{{ domain }}/{{ url|safe }}" style="background-color: #4CAF50; color: white; text-decoration: none; padding: 10px 20px; border-radius: 5px; font-size: 16px; display: inline-block;">
                    {% trans "Activate Account" %}
                </a>
            </p>
            <p style="font-size: 16px; color: #333;">
                {% trans "Thanks for using our site!" %}
            </p>
            <p style="font-size: 16px; color: #333; font-weight: bold;">
                {% blocktrans %}The {{ site_name }} team{% endblocktrans %}
            </p>
        </div>
        <div style="background-color: #f1f1f1; color: #999; text-align: center; padding: 10px; font-size: 12px;">
            {% trans "If you did not request this email, you can safely ignore it." %}
        </div>
    </div>
</div>
{% endblock html_body %}

Then create email.py file in accounts directory
accounts/email.py

from djoser import email


class ActivationEmail(email.ActivationEmail):
    template_name = 'email/activation_email.html'

To customize the site name in the template, add this line to the djoser setting

DJOSER = {
    "LOGIN_FIELD": "email",
    "EMAIL_FRONTEND_SITE_NAME": 'My App',  # Add this line
    "SEND_ACTIVATION_EMAIL": True,
    "ACTIVATION_URL": "accounts/activation/{uid}/{token}/",
    "SEND_CONFIRMATION_EMAIL": True,
    "EMAIL": {
        "activation": "accounts.email.ActivationEmail",
    },
}

The email template looks like this now

Extending Activation View

For the last part of this article, let work on the email verification.
We start by customizing the activation view in accounts/views.py:

accounts/views.py

from rest_framework.response import Response
from rest_framework import status
from djoser.views import UserViewSet


# Create your views here.


class ActivationView(UserViewSet):
    def activation(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = serializer.user
        user.is_verified = True
        user.save()
        super().activation(request, *args, **kwargs)
        return Response(
            {"message": "Account activated successfully and verified!"},
            status=status.HTTP_200_OK,
        )

We are extending the activation view on djoser to customize it and set the is_verified field on our user model to true

accounts/urls.py

from django.urls import path
from accounts.views import ActivationView


urlpatterns = [
    path("accounts/activation/", ActivationView.as_view({'post': 'activation'}), name="email-activation")
]

Urls file in the project level
userauth/urls.py

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/docs/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('api/', include('djoser.urls')), 
    path('api/', include('djoser.urls.jwt')),
    path('api/', include('accounts.urls'))   # Add this line
]

To test this out create a new test user and click the activation url sent to the email.
You get to this page, because the url does not exist in our project

from the url extract the uid and token and make a post request to the activation route you defined in your accounts/urls.py file

from the screenshot, my route is ;

http://127.0.0.1:8000/accounts/verify/MTY/cil456-aaf8331efb885f0b4412f35ce544648c/

The uid is MTY
The token is cil456-aaf8331efb885f0b4412f35ce544648c

Using the parameters to make a post request to the activate endpoint

This concludes the tutorial for setting up user authentication with Djoser. You now have a functional authentication system with email activation and customizable templates. In the second part of this series, we’ll explore social authentication, enabling users to sign up and log in using third-party services like Google, Facebook, and GitHub. Stay tuned for more!

If you have any questions or feedback, feel free to leave a comment.