Skip to main content

Django Built-in Middleware

Introduction​

Middleware in Django is a framework of hooks into Django's request/response processing. It's a lightweight, low-level plugin system for globally altering Django's input or output. Each middleware component is responsible for doing some specific function, like handling sessions, managing authentication, or compressing content.

Django comes with several built-in middleware classes that provide important functionality out of the box. These middleware components are configured in your project's settings and are executed in a specific order during the request-response cycle.

In this tutorial, we'll explore Django's built-in middleware components, understand what each one does, and learn how to configure them properly for your applications.

Understanding Django's Middleware Execution Flow​

Before diving into specific middleware, it's important to understand how middleware works in Django:

  1. When Django receives a request, it applies middleware in the order specified in the MIDDLEWARE setting
  2. Each middleware can process the request and pass it to the next middleware in the chain
  3. Once the request reaches the view and a response is generated, middleware is applied in reverse order
  4. Each middleware can process or modify the response before it's sent to the user

Here's a visual representation of the middleware flow:

Request → Middleware 1 → Middleware 2 → ... → View → ... → Middleware 2 → Middleware 1 → Response

Default Middleware Settings​

When you create a new Django project using django-admin startproject, Django automatically adds a set of middleware classes to your settings.py file:

python
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

Let's explore each of these built-in middleware components in detail.

SecurityMiddleware​

Purpose​

SecurityMiddleware provides several security enhancements to Django applications, helping to protect your site against various common web vulnerabilities.

Key Features​

  1. SSL/HTTPS Redirection: Forces all requests to be served over HTTPS
  2. HSTS (HTTP Strict Transport Security): Instructs browsers to only connect via HTTPS
  3. Content-Security-Policy: Helps prevent XSS attacks
  4. Referrer-Policy: Controls how much referrer information is sent
  5. X-Content-Type-Options: Prevents MIME type sniffing

Configuration​

You can configure SecurityMiddleware through several settings in your settings.py file:

python
# Redirect all HTTP requests to HTTPS
SECURE_SSL_REDIRECT = True

# Set the HSTS header
SECURE_HSTS_SECONDS = 3600  # 1 hour
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True

# Prevent browsers from MIME type sniffing
SECURE_CONTENT_TYPE_NOSNIFF = True

# Configure Content-Security-Policy header
SECURE_REFERRER_POLICY = 'same-origin'

Practical Example​

Let's say you want to ensure your application only serves content over HTTPS. Here's how you would configure it:

python
# settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    # Other middleware...
]

# Security settings
SECURE_SSL_REDIRECT = True
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')

With these settings, any HTTP request will be redirected to HTTPS automatically.

SessionMiddleware​

Purpose​

SessionMiddleware enables session support in Django applications, allowing you to store and retrieve arbitrary data on a per-site-visitor basis.

Key Features​

  1. Session Storage: Manages session data for users
  2. Cookie Handling: Sets and reads session cookies
  3. Session Expiration: Handles session expiry according to your settings

Configuration​

You can configure session behavior through several settings:

python
# Use database-backed sessions (default)
SESSION_ENGINE = 'django.contrib.sessions.backends.db'

# Or use file-based sessions
# SESSION_ENGINE = 'django.contrib.sessions.backends.file'

# Or cache-based sessions
# SESSION_ENGINE = 'django.contrib.sessions.backends.cache'

# Session cookie settings
SESSION_COOKIE_AGE = 1209600  # 2 weeks in seconds
SESSION_COOKIE_SECURE = True  # Only send cookies over HTTPS
SESSION_COOKIE_HTTPONLY = True  # Prevent JavaScript access to session cookie

Practical Example​

Here's how you might use sessions in a view after SessionMiddleware processes the request:

python
def my_view(request):
    # Get a value from the session
    visit_count = request.session.get('visit_count', 0)
    
    # Increment the value
    visit_count += 1
    
    # Store the value in the session
    request.session['visit_count'] = visit_count
    
    return render(request, 'my_template.html', {
        'visit_count': visit_count,
    })

In this example, we're tracking how many times a user has visited a particular page by storing a counter in their session.

CommonMiddleware​

Purpose​

CommonMiddleware provides several common features that don't neatly fit into other middleware categories.

Key Features​

  1. URL Rewriting: Handles URL rewrites based on APPEND_SLASH and PREPEND_WWW settings
  2. ETags: Can set the ETag header for responses to enable caching
  3. Prohibited User Agents: Can block requests from specified user agents

Configuration​

Common settings for this middleware include:

python
# Append a slash to URLs that don't have one
APPEND_SLASH = True

# Prepend 'www.' to URLs that don't have it
PREPEND_WWW = False

# Use ETags for browser caching
USE_ETAGS = True

Practical Example​

By default, Django will redirect URLs without a trailing slash to the same URL with a trailing slash. For example, if a user visits http://example.com/about, they'll be redirected to http://example.com/about/.

This is controlled by the APPEND_SLASH setting and handled by CommonMiddleware:

python
# settings.py
APPEND_SLASH = True  # This is the default

# Example URL pattern
urlpatterns = [
    path('about/', views.about_view, name='about'),
]

With this configuration, requests to /about will be redirected to /about/ automatically.

CsrfViewMiddleware​

Purpose​

CsrfViewMiddleware adds protection against Cross Site Request Forgeries (CSRF) by ensuring that POST, PUT, PATCH, and DELETE requests include a valid CSRF token.

Key Features​

  1. CSRF Token Validation: Verifies that requests include a valid CSRF token
  2. Form Protection: Automatically works with Django's form system
  3. AJAX Support: Works with AJAX requests via custom headers

Configuration​

You can configure CSRF protection with these settings:

python
# Cookie settings
CSRF_COOKIE_SECURE = True  # Only send over HTTPS
CSRF_COOKIE_HTTPONLY = True  # Prevent JavaScript access
CSRF_COOKIE_SAMESITE = 'Lax'  # SameSite cookie setting

# Where to redirect on failure
CSRF_FAILURE_VIEW = 'myapp.views.csrf_failure'

Practical Example​

In your Django templates, you need to include the CSRF token in forms:

html
<form method="post" action="/process/">
    {% csrf_token %}
    <!-- form fields -->
    <button type="submit">Submit</button>
</form>

For AJAX requests, you need to include the token in your headers:

javascript
// JavaScript example using fetch API
const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;

fetch('/api/endpoint/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRFToken': csrftoken,
    },
    body: JSON.stringify({ key: 'value' })
})
.then(response => response.json())
.then(data => console.log(data));

AuthenticationMiddleware​

Purpose​

AuthenticationMiddleware associates users with requests using Django's authentication system.

Key Features​

  1. User Association: Associates the user attribute to the request object
  2. Anonymous Users: Sets request.user to an AnonymousUser instance if the user isn't authenticated
  3. Session Integration: Works with SessionMiddleware to associate users with sessions

Configuration​

This middleware has no specific settings of its own, but works with Django's authentication framework:

python
# Authentication backends
AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',
]

# Auth user model (if you're using a custom user model)
AUTH_USER_MODEL = 'myapp.CustomUser'

Practical Example​

Once AuthenticationMiddleware is active, you can easily check if a user is authenticated in your views:

python
def profile_view(request):
    if request.user.is_authenticated:
        # Show the user's profile
        return render(request, 'profile.html', {
            'user': request.user,
        })
    else:
        # Redirect to login page
        return redirect('login')

You can also use Django's decorators to require authentication:

python
from django.contrib.auth.decorators import login_required

@login_required
def dashboard_view(request):
    # This view will only be accessible to authenticated users
    return render(request, 'dashboard.html')

MessageMiddleware​

Purpose​

MessageMiddleware enables the use of Django's messaging framework, which provides a way to store messages during processing for display to users in subsequent requests.

Key Features​

  1. Message Storage: Handles storing and retrieving messages
  2. Multiple Storage Backends: Supports storing messages in sessions, cookies, etc.
  3. Message Levels: Supports different message types (debug, info, success, warning, error)

Configuration​

You can configure the message framework with these settings:

python
# Message storage backend
MESSAGE_STORAGE = 'django.contrib.messages.storage.session.SessionStorage'

# Message tags (for CSS classes)
from django.contrib.messages import constants as messages
MESSAGE_TAGS = {
    messages.DEBUG: 'alert-info',
    messages.INFO: 'alert-info',
    messages.SUCCESS: 'alert-success',
    messages.WARNING: 'alert-warning',
    messages.ERROR: 'alert-danger',
}

Practical Example​

Here's how to use messages in a view:

python
from django.contrib import messages

def update_profile(request):
    if request.method == 'POST':
        form = ProfileForm(request.POST, instance=request.user.profile)
        if form.is_valid():
            form.save()
            messages.success(request, "Your profile has been updated!")
            return redirect('profile')
        else:
            messages.error(request, "Please correct the errors below.")
    else:
        form = ProfileForm(instance=request.user.profile)
    
    return render(request, 'edit_profile.html', {'form': form})

And in your template, display the messages:

html
{% if messages %}
<ul class="messages">
    {% for message in messages %}
    <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
    {% endfor %}
</ul>
{% endif %}

XFrameOptionsMiddleware​

Purpose​

XFrameOptionsMiddleware helps prevent clickjacking attacks by including the X-Frame-Options header in HTTP responses.

Key Features​

  1. Clickjacking Protection: Prevents your site from being embedded in iframes on other sites
  2. Configurable Policy: Allows you to specify whether your site can be framed by the same origin or not at all

Configuration​

You can configure this middleware with these settings:

python
# Default: 'SAMEORIGIN'
X_FRAME_OPTIONS = 'DENY'  # Or 'SAMEORIGIN'

# Exempt specific views
from django.http import HttpResponse
from django.views.decorators.clickjacking import xframe_options_exempt

@xframe_options_exempt
def my_view(request):
    return HttpResponse("This view can be embedded in an iframe")

Practical Example​

By default, XFrameOptionsMiddleware sets the X-Frame-Options header to SAMEORIGIN, which allows your pages to be framed by other pages on your own domain.

If you want to completely prevent your site from being framed:

python
# settings.py
X_FRAME_OPTIONS = 'DENY'

If you need certain views to be embeddable in iframes (e.g., for a widget):

python
from django.views.decorators.clickjacking import xframe_options_exempt

@xframe_options_exempt
def widget_view(request):
    """This view can be embedded in iframes on other sites."""
    return render(request, 'widget.html')

Other Built-in Middleware​

Django also includes several other middleware classes that aren't enabled by default:

GZipMiddleware​

Compresses responses for browsers that support gzip compression.

python
MIDDLEWARE = [
    'django.middleware.gzip.GZipMiddleware',
    # Other middleware...
]

LocaleMiddleware​

Enables language selection based on request data.

python
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.locale.LocaleMiddleware',  # Add after SessionMiddleware
    'django.middleware.common.CommonMiddleware',
    # Other middleware...
]

ConditionalGetMiddleware​

Handles conditional GET operations.

python
MIDDLEWARE = [
    # Other middleware...
    'django.middleware.http.ConditionalGetMiddleware',
]

Customizing Middleware Settings​

Here's a more comprehensive example of middleware settings for a production application:

python
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.middleware.gzip.GZipMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.locale.LocaleMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'django.middleware.http.ConditionalGetMiddleware',
]

# Security settings
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000  # 1 year
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_CONTENT_TYPE_NOSNIFF = True
SECURE_BROWSER_XSS_FILTER = True
SECURE_REFERRER_POLICY = 'same-origin'
X_FRAME_OPTIONS = 'DENY'

# Session settings
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = 'Lax'

# CSRF settings
CSRF_COOKIE_SECURE = True
CSRF_COOKIE_HTTPONLY = True
CSRF_COOKIE_SAMESITE = 'Lax'

Real-world Application: E-commerce Site​

Let's see how built-in middleware might be used in a real-world e-commerce application:

python
# settings.py for an e-commerce site

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',  # For HTTPS redirection and security headers
    'django.middleware.gzip.GZipMiddleware',  # For compressing responses, improving load times
    'django.contrib.sessions.middleware.SessionMiddleware',  # For shopping cart sessions
    'django.middleware.locale.LocaleMiddleware',  # For multi-language support
    'django.middleware.common.CommonMiddleware',  # For URL normalization
    'django.middleware.csrf.CsrfViewMiddleware',  # For form security
    'django.contrib.auth.middleware.AuthenticationMiddleware',  # For user accounts
    'django.contrib.messages.middleware.MessageMiddleware',  # For order confirmations
    'django.middleware.clickjacking.XFrameOptionsMiddleware',  # For security
    
    # Custom middleware for the shop
    'myshop.middleware.CartMiddleware',  # Custom middleware for shopping cart
    'myshop.middleware.RecentlyViewedMiddleware',  # Track recently viewed products
]

# Security is crucial for e-commerce
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000  # 1 year
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

In this e-commerce application:

  1. SecurityMiddleware ensures transactions happen over HTTPS
  2. SessionMiddleware and custom CartMiddleware manage the shopping cart
  3. LocaleMiddleware provides multi-language support for international customers
  4. MessageMiddleware displays order confirmations and other notifications
  5. AuthenticationMiddleware manages user accounts and purchase history

Summary​

Django's built-in middleware provides a robust set of features for handling common web application needs:

  1. Security: Protection against various attacks with SecurityMiddleware and XFrameOptionsMiddleware
  2. Sessions: User session management with SessionMiddleware
  3. Authentication: User authentication with AuthenticationMiddleware
  4. CSRF Protection: Form security with CsrfViewMiddleware
  5. URL Processing: URL normalization with CommonMiddleware
  6. User Notifications: Flash messages with MessageMiddleware
  7. Performance: Response compression with GZipMiddleware

These middleware components work together to handle many aspects of web request processing automatically, allowing you to focus on building your application's unique features.

Additional Resources​

To learn more about Django middleware:

  1. Django Middleware Documentation
  2. Django Security Best Practices
  3. Django Sessions Framework
  4. Writing Custom Middleware

Exercises​

  1. Enable GZipMiddleware in your Django project and measure the performance improvement using browser developer tools.
  2. Configure SecurityMiddleware with appropriate settings for a production application.
  3. Create a view that uses Django's messaging framework to display notifications to users.
  4. Write a custom middleware that logs the time taken to process each request and response.
  5. Configure LocaleMiddleware to support multiple languages in your application.

By mastering Django's built-in middleware, you'll be able to leverage powerful features for security, performance, and usability without reinventing the wheel.


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)