How to Implement JWT Authentication in Django REST Framework (Without the Headache)

Adham Emam — Tue, 20 May 2025 22:56:08 +0000

Introduction
What is JWT
Why Use JWT
Structure of a JWT
Installation and Setup
Customizing the Response
Summary

Introduction

Searching for a secured way to implement an authentication system in your application can be challenging — but worries aside, we will break down the concept and how to implement JWT tokens (JSON Web Token) on you application.

Since you are reading this I’ll assume you already know some Python or interested in learning about it.

Soooo…
I’ll be using the most powerful Python web framework — Django REST Framework — to demonstrate everything with practical examples, and at the end of this article you are going to have a secure Django API with a custom user model and JWT secure API authentication.

What is JWT

JSON Web token is a standard practice to authenticate users, confirm their identities, and guarantee secure communication between the client (the Frontend) and the server (the Backend) using a JSON Web token, a standard for securely sharing data between the two. Web apps and APIs mostly employ JWTs to guard against unwanted access.

A simple JSON format is used to store the contents in a JWT, including user information. The token is cryptographically signed to ensure that no one can change the data.

Why use JWT

There is a lot of ways for authentication Tokens are one of them — but why use it? JWT Token comes with a lot of Pros that makes it tempting for developer to use it in their applications — and of course comes with some cons so lets break it down.

✅ Pros

No Need to Store Sessions on the Server

The server doesn't have to remember who you are because all the information is in the JWT you carry.
Works Across Different Services

JWTs can be used across multiple websites or services, making it easier to manage logins in complex systems.
Quick Verification

Since the JWT contains all the necessary information, the server can quickly verify your identity without checking a database.
Secure Information Exchange

JWTs are signed, so the server can ensure that the information hasn't been tampered with.

🚫 Cons

Can't Easily Revoke Tokens

Once a JWT is issued, it's valid until it expires. If someone logs out or needs their access revoked, it's not straightforward to invalidate the token.
Sensitive to Secret Key Leaks

If the secret key used to sign the JWT is compromised, attackers can create fake tokens.
Token Size Can Be Large

JWTs can become large if they carry a lot of information, which might slow down network requests.
No Built-in Logout Mechanism

JWTs don't have a way to log out users immediately. The token remains valid until it expires.

So to sorts things up JWT are useful for stateless authentication, meaning the server doesn't need to keep track of users. They're efficient and work well across different services. However, they require careful handling, especially regarding security and token management.

Structure of a JWT

A JWT is composed of three parts, separated by dots (.):

Header: Contains metadata about the token, including the type of token and the algorithm used for signing.

Example:
```
{
  "alg": "HS256",
  "typ": "JWT"
}
```
Payload: Holds the claims or statements about an entity (typically, the user) and additional data.

Example:
```
{
  "userId": 123,
  "role": "admin",
  "exp": 1672531199
}
```
Common claims include:

- `iss` (Issuer): Identifies who issued the token.
- `sub` (Subject): Identifies the subject of the token.
- `aud` (Audience): Identifies the recipients the token is intended for.
- `exp` (Expiration Time): Identifies the expiration time on or after which the token must not be accepted.
- `iat` (Issued At): Identifies the time at which the token was issued.
- `nbf` (Not Before): Identifies the time before which the token must not be accepted.

Signature: Ensures that the token hasn't been altered. It's created by encoding the header and payload, then signing them using a secret key and the algorithm specified in the header.(JWT)

Example using HMAC SHA256:
```
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret
)
```

Final JWT Token

After encoding the header and payload, and generating the signature, the JWT looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJ1c2VySWQiOjEyMywicm9sZSI6ImFkbWluIiwiZXhwIjoxNjcyNTMxMTk5fQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Each part is Base64Url encoded and separated by dots.(Okta Developer)

Installation

Let’s now start by installing djangorestframework-simplejwt and create our authentication.

Install Required Packages

pip install django djangorestframework djangorestframework-simplejwt

Django allows you to define a custom user model to suit your application's needs. Here's how you can create one:

models.py

from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin, BaseUserManager
from django.db import models

class CustomUserManager(BaseUserManager):
    def create_user(self, email, password=None, **extra_fields):
        if not email:
            raise ValueError("The Email field must be set")
        email = self.normalize_email(email)  # Make email lowercase
        user = self.model(email=email, **extra_fields)  # Create user instance
        user.set_password(password)  # Hash the password
        user.save(using=self._db)  # Save to database
        return user

    def create_superuser(self, email, password=None, **extra_fields):
        extra_fields.setdefault('is_staff', True)
        extra_fields.setdefault('is_superuser', True)
        return self.create_user(email, password, **extra_fields)

class CustomUser(AbstractBaseUser, PermissionsMixin):
    email = models.EmailField(unique=True)
    first_name = models.CharField(max_length=30, blank=True)
    last_name = models.CharField(max_length=30, blank=True)
    is_active = models.BooleanField(default=True)
    is_staff = models.BooleanField(default=False)

    objects = CustomUserManager()

    USERNAME_FIELD = 'email' # Set login with email instead of username
    REQUIRED_FIELDS = ['first_name', 'last_name']

Update Settings

In your project's settings.py, make the following adjustments:

Specify the custom user model:

AUTH_USER_MODEL = 'users.CustomUser' # Or replace user with your users app name

Add required apps:

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'rest_framework_simplejwt',
    'users', 
]

Configure REST Framework and Simple JWT:

from datetime import timedelta

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

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60), # Token valid for 60 minutes
    'REFRESH_TOKEN_LIFETIME': timedelta(days=7), # Refresh valid for 7 day
    'ROTATE_REFRESH_TOKENS': False,
    'BLACKLIST_AFTER_ROTATION': False,
    'ALGORITHM': 'HS256',
    'SIGNING_KEY': SECRET_KEY, # Use Django's secret key
    'AUTH_HEADER_TYPES': ('Bearer',),
}

Apply Migrations

After defining your custom user model, create and apply migrations:
```
python manage.py makemigrations
python manage.py migrate
```

Set URLs for your Application

api/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("users/", include("users.urls")), # Add This
]

Set Up JWT Authentication Endpoints

Simple JWT provides views for obtaining and refreshing tokens. Include them in your project's

users/urls.py

from django.urls import path
from rest_framework_simplejwt.views import (
    TokenObtainPairView,  # View to get access + refresh tokens
    TokenRefreshView      # View to refresh access token
)

urlpatterns = [
    # ...
    path('token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

Create your First User

Create an admin user to test the login functionality
```
python manage.py createsuperuser
```
Run The Application

Now you are ready to run the application and test the endpoint
```
python manage.py runserver 
```
this will run your application on your browser , now by visiting this URL http://127.0.0.1:8000/users/token and entering the credentials you just create you should see a response like this
```
{
  "access": "your_access_token",
  "refresh": "your_refresh_token"
}
```

Now you have an access token that refers to the current user and a refresh token that is used to get a new access token once the current access is expired — and if the refresh is expired the user should login again to get new refresh and access, sounds more simple now right!

also you can use to make API calls by adding it to the header:

Authorization: Bearer your_access_token

Customizing the Response (Optional)

You can also customize the the response that you get by adding more data to prevent multiple requests from the server by creating token.py on your users app and add this code

from rest_framework_simplejwt.tokens import Token, AccessToken

class CustomAccessToken(AccessToken):
    @classmethod
    def for_user(cls, user):
        token = super().for_user(user)

        # Add custom claims here
        token["email"] = user.email
        token["is_staff"] = user.is_staff
        token["first_name"] = user.first_name
        token["last_name"] = user.last_name

        return token

this is going to override the response coming form this endpoint — and should look this:

{
  "access": "your_access_token",
  "refresh": "your_refresh_token"
    "user": {
        "id": 1,
        "email": "user's_email",
        "first_name": "first_name",
        "last_name": "last_name"
        }
}

Summary

Implementing JWT authentication in your Django REST Framework project might seem intimidating at first, but once you understand how tokens work and follow the right setup, it becomes a powerful and flexible solution for securing your APIs.

With JWT, you get stateless authentication, scalability, and faster request handling — all without the overhead of managing server-side sessions. Just remember that with great power comes great responsibility: always protect your secret keys, set appropriate token lifetimes, and be cautious with sensitive data in the payload.

Now that you’ve completed the setup, tested the endpoints, and even customized your token responses — you’ve taken a big step toward building modern, secure, and scalable Django applications.

Happy coding fellas!

DEV Community: Adham Emam