Table of Contents
- 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.([Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token?utm_source=chatgpt.com))
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!
SOCIAL SHARE CARD GENERATOR