Blog

When you want to let users log in to your Python web application using their GitHub accounts, the GitHub OAuth authentication flow is the industry‑standard solution. It enables you to securely obtain an access token, fetch user data, and personalize the experience without ever handling passwords directly. In this guide we’ll walk through every step of the Python GitHub OAuth authentication flow, from registering your app on GitHub to writing clean, production‑ready code with Flask (or any WSGI framework). By the end you’ll have a solid, SEO‑friendly reference that you can copy‑paste into your own projects.

Why Choose GitHub OAuth for Python Projects?

• Secure delegation: Users authenticate on GitHub, not on your server.
• Rich developer data: Access public profile, email, repositories, and more.
• Standardized protocol: OAuth 2.0 is widely supported and well‑documented.
• Python ecosystem: Libraries like requests, authlib, and Flask‑Login simplify implementation.

Prerequisites Before You Start

• Python 3.8+ installed on your development machine.
• A GitHub account (obviously) and permission to create OAuth apps.
• Basic familiarity with a Python web framework (Flask, Django, FastAPI, etc.).
• Installed dependencies:

  pip install Flask requests authlib

Step 1: Register Your OAuth Application on GitHub

Creating the app

1. Navigate to GitHub Settings → Developer settings → OAuth Apps.
2. Click New OAuth App.
3. Fill in the required fields:
   • Application name: e.g., MyPythonApp
   • Homepage URL: https://myapp.example.com/
   • Authorization callback URL: https://myapp.example.com/auth/callback
4. Save the app. GitHub will generate a Client ID and a Client Secret**. Store them securely (environment variables are recommended).

Step 2: Understanding the OAuth 2.0 Flow

GitHub follows the standard Authorization Code Grant flow. The sequence is:

1. Authorization request: Your app redirects the user to GitHub’s consent page.
2. User grants permission: GitHub asks the user to approve the requested scopes.
3. Redirect with code: GitHub redirects back to your callback URL with a temporary code parameter.
4. Token exchange: Your server sends the code, client ID, and client secret to GitHub’s token endpoint.
5. Access token received: GitHub returns a JSON payload containing the access_token.
6. API calls: Use the token in the Authorization: token <access_token> header to fetch user data.

Step 3: Implementing the Flow in Python

Project structure

.
├─ app.py               # Main Flask application
├─ config.py            # Environment variables & settings
└─ requirements.txt    # Dependencies

Configuration (config.py)

import os

class Config:
    GITHUB_CLIENT_ID = os.getenv('GITHUB_CLIENT_ID')
    GITHUB_CLIENT_SECRET = os.getenv('GITHUB_CLIENT_SECRET')
    SECRET_KEY = os.getenv('FLASK_SECRET_KEY', 'dev-secret')
    # The URL where GitHub will redirect after auth
    GITHUB_REDIRECT_URI = os.getenv('GITHUB_REDIRECT_URI',
                                    'http://localhost:5000/auth/callback')
    # Scopes you need – adjust as required
    GITHUB_OAUTH_SCOPE = 'read:user user:email'

Flask application (app.py)

from flask import Flask, redirect, url_for, request, session, jsonify
import requests
from authlib.integrations.flask_client import OAuth
from config import Config

app = Flask(__name__)
app.config.from_object(Config)

# Initialize OAuth registry
oauth = OAuth(app)
github = oauth.register(
    name='github',
    client_id=app.config['GITHUB_CLIENT_ID'],
    client_secret=app.config['GITHUB_CLIENT_SECRET'],
    access_token_url='https://github.com/login/oauth/access_token',
    authorize_url='https://github.com/login/oauth/authorize',
    api_base_url='https://api.github.com/',
    client_kwargs={'scope': app.config['GITHUB_OAUTH_SCOPE']},
)

@app.route('/')
def index():
    user = session.get('github_user')
    if user:
        return f\"
Welcome, {user['login']}!
Logout
\"
    return \"
Python GitHub OAuth Demo
Login with GitHub\"

@app.route('/login')
def login():
    # Step 1 – redirect user to GitHub's consent page
    redirect_uri = url_for('auth_callback', _external=True)
    return github.authorize_redirect(redirect_uri)

@app.route('/auth/callback')
def auth_callback():
    # Step 4 – exchange the temporary code for an access token
    token = github.authorize_access_token()
    # Store token securely (session is fine for demo)
    session['github_token'] = token

    # Step 5 – fetch user profile
    resp = github.get('user')
    profile = resp.json()
    session['github_user'] = profile

    # Optional: fetch primary email if not public
    if not profile.get('email'):
        emails_resp = github.get('user/emails')
        emails = emails_resp.json()
        primary = next((e['email'] for e in emails if e['primary']), None)
        session['github_user']['email'] = primary

    return redirect(url_for('index'))

@app.route('/logout')
def logout():
    session.clear()
    return redirect(url_for('index'))

if __name__ == '__main__':
    app.run(debug=True)

Key points in the code

• Redirect URI is built dynamically with url_for(..., _external=True) so it works locally and in production.
• github.authorize_redirect() automatically adds client_id, redirect_uri, and scope to the URL.
• github.authorize_access_token() handles the POST request to GitHub’s token endpoint and parses the JSON response.
• All API calls use the same github client, which injects the Authorization header for you.

Step 4: Security Best Practices

• Never hard‑code client secrets. Use environment variables or a secret manager (AWS Secrets Manager, HashiCorp Vault, etc.).
• Use HTTPS for both your site and the callback URL. GitHub rejects insecure redirect URIs for production apps.
• Validate the state parameter if you implement it manually. authlib does this automatically, but custom implementations should generate a random nonce, store it in the session, and compare it on callback.
• Limit scopes to the minimum required. Requesting repo when you only need read:user raises unnecessary risk.
• Rotate client secrets periodically and revoke tokens when users log out or when suspicious activity is detected.

Common Pitfalls & How to Debug Them

1. Redirect URI mismatch – GitHub will return a redirect_uri mismatch error if the URL you send does not exactly match the one registered. Double‑check trailing slashes and protocol (http vs https).
2. Missing state validation – If you turn off authlib’s built‑in state handling, CSRF attacks become possible. Always verify the state you sent.
3. Rate limiting – Unauthenticated GitHub API calls are limited to 60 requests/hour. Use the access token for higher limits (5,000 requests/hour per user).
4. Expired authorization code – The temporary code is valid for only a few minutes. Ensure you exchange it immediately in the callback route.
5. Incorrect token parsing – GitHub returns the token as application/x-www-form-urlencoded by default. Libraries like requests handle it, but if you parse manually, use response.json() or urllib.parse.parse_qs.

Testing the Flow Locally

During development you can use http://localhost:5000/auth/callback as the redirect URI. GitHub allows localhost URLs, but remember to switch to a fully qualified domain with HTTPS before going live. Tools like ngrok can expose your local server to the internet for quick integration tests.

Deploying to Production

• Set FLASK_ENV=production and configure a WSGI server (Gunicorn, uWSGI).

Integrating Google OAuth2 login into a Python web application is one of the most effective ways to provide a seamless, secure, and frictionless authentication experience for users. By leveraging Google’s trusted identity platform, developers can offload password management, reduce signup friction, and boost conversion rates—all while keeping their codebase clean and maintainable. In this guide, we’ll walk through the entire process: from setting up a Google Cloud project to implementing OAuth2 in both Flask and Django, handling tokens securely, and troubleshooting common pitfalls. Whether you’re building a small prototype or a production‑grade SaaS, the steps below will give you a solid foundation for Python Google OAuth2 login integration.

Why Choose Google OAuth2 for Your Python App?

• Trusted security: Google’s infrastructure follows industry‑leading security standards, including multi‑factor authentication and anomaly detection.
• Reduced password fatigue: Users can sign in with an existing Google account, eliminating the need to remember another password.
• Rich user profile data: With a single consent screen, you can retrieve email, name, profile picture, and even locale information.
• Scalable and future‑proof: OAuth2 is the de‑facto standard for modern authentication, making it easy to add other providers later (e.g., Facebook, GitHub).

Prerequisites

1. Basic knowledge of Python and a web framework (Flask or Django).
2. Python 3.8+ installed on your development machine.
3. A Google account to access the Google Cloud Console.
4. Virtual environment tool (venv, pipenv, or poetry) for dependency isolation.

Step 1: Create a Google Cloud Project and OAuth2 Credentials

1.1 Enable the Google Identity Services API

Log in to the Google Cloud Console, create a new project (or select an existing one), and navigate to APIs & Services > Library. Search for Google Identity Services API and click Enable.

1.2 Configure OAuth Consent Screen

Under APIs & Services > OAuth consent screen, choose External for public apps. Fill in the required fields:

• App name, support email, and developer contact information.
• Scopes you need (e.g., email, profile, openid).
• Authorized domains (e.g., localhost for development, your production domain for live).

Save the consent screen; Google will review it if you request sensitive scopes.

1.3 Generate Client ID and Client Secret

Go to Credentials > Create Credentials > OAuth client ID. Choose Web application and set the following:

• Authorized JavaScript origins: http://localhost:5000 (Flask) or http://127.0.0.1:8000 (Django).
• Authorized redirect URIs: http://localhost:5000/auth/callback (Flask) or http://127.0.0.1:8000/oauth2callback/ (Django).

After creation, note the Client ID and Client Secret. Store them securely (e.g., in .env).

Step 2: Install Required Python Packages

Both Flask and Django have mature extensions for OAuth2. The most popular choices are Authlib and python-social-auth. Below we’ll use Authlib for its simplicity and modern API.

pip install Flask Authlib        # For Flask projects
pip install Django Authlib       # For Django projects
pip install python-dotenv        # Optional: load .env files

Step 3: Implement Google OAuth2 in Flask

3.1 Project Structure

.
├─ app.py
├─ templates/
│  ├─ login.html
│  └─ profile.html
└─ .env

3.2 .env File (Never commit secrets)

GOOGLE_CLIENT_ID=YOUR_CLIENT_ID.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET
SECRET_KEY=your_flask_secret_key

3.3 Flask Application Code

from flask import Flask, redirect, url_for, session, render_template, request
from authlib.integrations.flask_client import OAuth
from dotenv import load_dotenv
import os

load_dotenv()  # Load .env variables

app = Flask(__name__)
app.secret_key = os.getenv('SECRET_KEY')

# Configure OAuth
oauth = OAuth(app)
google = oauth.register(
    name='google',
    client_id=os.getenv('GOOGLE_CLIENT_ID'),
    client_secret=os.getenv('GOOGLE_CLIENT_SECRET'),
    access_token_url='https://oauth2.googleapis.com/token',
    authorize_url='https://accounts.google.com/o/oauth2/v2/auth',
    client_kwargs={'scope': 'openid email profile'},
)

@app.route('/')
def index():
    user = session.get('user')
    return render_template('login.html', user=user)

@app.route('/login')
def login():
    redirect_uri = url_for('auth_callback', _external=True)
    return google.authorize_redirect(redirect_uri)

@app.route('/auth/callback')
def auth_callback():
    token = google.authorize_access_token()
    resp = google.get('userinfo')
    user_info = resp.json()
    # Store user info in session (or DB for production)
    session['user'] = {
        'id': user_info['sub'],
        'name': user_info['name'],
        'email': user_info['email'],
        'picture': user_info['picture'],
    }
    return redirect(url_for('profile'))

@app.route('/profile')
def profile():
    user = session.get('user')
    if not user:
        return redirect(url_for('index'))
    return render_template('profile.html', user=user)

@app.route('/logout')
def logout():
    session.clear()
    return redirect(url_for('index'))

if __name__ == '__main__':
    app.run(debug=True)

3.4 Template Snippets

login.html

<!DOCTYPE html>
<html>
<body>
    {% if user %}
        <p>Welcome, <strong>{{ user.name }}</strong>!</p>
        <a href="{{ url_for('profile') }}">View Profile</a>
        <a href="{{ url_for('logout') }}">Logout</a>
    {% else %}
        <a href="{{ url_for('login') }}">Sign in with Google</a>
    {% endif %}
</body>
</html>

profile.html

<!DOCTYPE html>
<html>
<body>
    <h2>User Profile</h2>
    <img src="{{ user.picture }}" alt="Profile picture" width="100">
    <p><strong>Name: {{ user.name }}</p>
    <p><strong>Email: {{ user.email }}</p>
    <a href="{{ url_for('logout') }}">Logout</a>
</body>
</html>

Step 4: Implement Google OAuth2 in Django

4.1 Project Setup

django-admin startproject mysite
cd mysite
python manage.py startapp accounts
pip install django-authlib python-dotenv

4.2 Settings Adjustments (mysite/settings.py)

import os
from dotenv import load_dotenv

load_dotenv()

SECRET_KEY = os.getenv('DJANGO_SECRET_KEY')
DEBUG = True
ALLOWED_HOSTS = []

INSTALLED_APPS = [
    # default apps …
    'django.contrib.sessions',
    'accounts',
]

MIDDLEWARE = [
    # default middleware …
    'django.contrib.sessions.middleware.SessionMiddleware',
]

# OAuth2 configuration
GOOGLE_CLIENT_ID = os.getenv('GOOGLE_CLIENT_ID')
GOOGLE_CLIENT_SECRET = os.getenv('GOOGLE_CLIENT_SECRET')

4.3 URL Configuration (mysite/urls.py)

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('accounts.urls')),
]

4.4 Accounts App URLs (accounts/urls.py)

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    path('login/', views.login, name='login'),
    path('oauth2callback/', views.auth_callback, name='auth_callback'),
    path('profile/', views.profile, name='profile'),
    path('logout/', views.logout_view, name='logout'),
]

4.5 Views Implementation (accounts/views.py)

from django.shortcuts import render, redirect

from django.conf import settings

from authlib.integrations.django_client import OAuth

from django.http import HttpResponse

oauth = OAuth()

google = oauth.register(

    name='google',

    client_id=settings.GOOGLE_CLIENT_ID,

    client_secret=settings.GOOGLE_CLIENT

Cross‑Origin Resource Sharing (CORS) is a cornerstone of modern web development, allowing browsers to safely request resources from a different domain than the one that served the page. If you’re building APIs or web services with Python, mastering CORS configuration is essential to keep your applications secure while delivering a seamless user experience. In this guide we’ll walk through the fundamentals of CORS, show you how to configure it in the three most popular Python frameworks—Flask, Django, and FastAPI—and share practical tips for testing and troubleshooting.

What Is CORS and How Does It Work?

CORS is a browser‑level security feature that controls which origins (domains, protocols, or ports) are permitted to read resources from a server. When a web page makes a cross‑origin request, the browser sends a Origin header. The server then decides whether to include an Access-Control-Allow-Origin header in its response. If the header matches the requesting origin (or is a wildcard *), the browser allows the response to be accessed by JavaScript; otherwise, it blocks the data.

Key CORS response headers

• Access-Control-Allow-Origin: Specifies the allowed origin(s). Example: Access-Control-Allow-Origin: https://example.com
• Access-Control-Allow-Methods: Lists HTTP methods permitted for the request (GET, POST, PUT, DELETE, etc.).
• Access-Control-Allow-Headers: Indicates which custom headers the client may send.
• Access-Control-Allow-Credentials: When set to true, cookies and HTTP authentication are allowed.
• Access-Control-Max-Age: Caches the pre‑flight response for a specified number of seconds.

Why Configure CORS in Python Applications?

Without proper CORS handling, your API may either:

• Reject legitimate requests from trusted front‑ends, breaking functionality.
• Expose sensitive data to malicious sites if you use a permissive wildcard configuration.

Python frameworks provide middleware or extensions that automate header management, letting you focus on business logic while maintaining security best practices.

Configuring CORS in Flask

Flask is lightweight, and the most common way to handle CORS is with the flask‑cors extension.

Step‑by‑step setup

1. Install the extension:

   pip install flask-cors

2. Import and initialize it in your application:

   from flask import Flask
   from flask_cors import CORS
   
   app = Flask(__name__)
   
   # Allow all origins (use with caution)
   CORS(app)
   
   # OR configure specific origins
   CORS(app, resources={
       r"/api/*": {"origins": ["https://frontend.example.com", "https://admin.example.com"]},
       r"/public/*": {"origins": "*"}
   })

3. Fine‑tune individual routes if needed:

   @app.route("/api/data")
   @cross_origin(origins="https://frontend.example.com", methods=["GET", "POST"])
   def get_data():
       return {"message": "CORS enabled for this endpoint"}

Best practices for Flask

• Never use * for Access-Control-Allow-Origin when Access-Control-Allow-Credentials is true.
• Restrict methods and headers to the minimum required.
• Separate public and private API namespaces and apply different CORS rules.

Configuring CORS in Django

Django’s built‑in middleware system makes CORS handling straightforward with the django-cors-headers package.

Installation and basic configuration

1. Add the package:

   pip install django-cors-headers

2. Update settings.py:

   INSTALLED_APPS = [
       ...,
       "corsheaders",
   ]
   
   MIDDLEWARE = [
       "corsheaders.middleware.CorsMiddleware",
       "django.middleware.common.CommonMiddleware",
       ...,
   ]
   
   # Allow only specific origins
   CORS_ALLOWED_ORIGINS = [
       "https://frontend.example.com",
       "https://admin.example.com",
   ]
   
   # Optional: allow all subdomains of a domain
   CORS_ALLOWED_ORIGIN_REGEXES = [
       r"^https://\w+\.example\.com$",
   ]
   
   # Enable credentials if needed
   CORS_ALLOW_CREDENTIALS = True
   
   # Restrict methods
   CORS_ALLOW_METHODS = [
       "GET",
       "POST",
       "PUT",
       "PATCH",
       "DELETE",
   ]

3. For per‑view control, use the decorator:

   from corsheaders.decorators import cors_allow_all, cors_allow_origin
   
   @cors_allow_origin("https://frontend.example.com")
   def my_view(request):
       ...

Tips for Django projects

• Place CorsMiddleware as high as possible in the middleware list to ensure headers are added before other processing.
• Combine CORS_ALLOW_ALL_ORIGINS = False with an explicit whitelist for tighter security.
• Leverage CORS_EXPOSE_HEADERS when you need the client to read custom response headers.

Configuring CORS in FastAPI

FastAPI, built on Starlette, uses a simple CORSMiddleware that can be added directly to the application instance.

Implementation steps

1. Install FastAPI and Uvicorn (if not already):

   pip install fastapi uvicorn

2. Add the middleware:

   from fastapi import FastAPI
   from fastapi.middleware.cors import CORSMiddleware
   
   app = FastAPI()
   
   origins = [
       "https://frontend.example.com",
       "https://admin.example.com",
   ]
   
   app.add_middleware(
       CORSMiddleware,
       allow_origins=origins,
       allow_credentials=True,
       allow_methods=["GET", "POST", "PUT", "DELETE"],
       allow_headers=["*"],  # Adjust as needed
       max_age=600,
   )

3. Define your routes normally; the middleware will handle CORS for all paths unless you create a separate APIRouter with its own settings.

FastAPI CORS checklist

• Use a list of origins instead of * when allow_credentials=True.
• Set max_age to reduce pre‑flight traffic for high‑traffic endpoints.
• When serving static files, remember that the same middleware applies unless you mount a separate StaticFiles instance with its own configuration.

Common Pitfalls and How to Avoid Them

Even seasoned developers can stumble over subtle CORS issues. Below are the most frequent mistakes and quick fixes.

1. Using a wildcard with credentials

Browsers reject responses that contain Access-Control-Allow-Credentials: true together with Access-Control-Allow-Origin: *. Always specify explicit origins when credentials are required.

2. Forgetting to handle pre‑flight OPTIONS requests

Some frameworks automatically respond to OPTIONS requests, but if you have custom routing logic you may need to add an explicit handler:

@app.route("/api/resource", methods=["OPTIONS"])
def options_handler():
    response = make_response()
    response.headers["Access-Control-Allow-Origin"] = "https://frontend.example.com"
    response.headers["Access-Control-Allow-Methods"] = "GET,POST,PUT,DELETE"
    response.headers["Access-Control-Allow-Headers"] = "Content-Type,Authorization"
    return response

3. Over‑exposing headers

Only expose the headers your client actually needs. Unnecessary exposure can leak internal implementation details.

4. Ignoring sub‑domain variations

If your front‑end uses dynamic sub‑domains (e.g., user1.example.com), use regex‑based origin matching instead of enumerating each sub‑domain.

Testing Your CORS Configuration

Automated testing ensures that CORS behaves as expected across environments.

Manual testing with browser dev tools

• Open the Network tab, make a cross‑origin request, and inspect the response headers.
• Look for Access-Control-Allow-Origin and verify it matches the request’s Origin.

Cross‑Site Request Forgery (CSRF) remains one of the most sneaky web vulnerabilities, and Python developers often wonder how to defend their applications without sacrificing performance or developer ergonomics. In this guide we’ll explore what CSRF is, why it matters, and how to implement rock‑solid protection in the most popular Python web frameworks—Django, Flask, and FastAPI. You’ll also learn the underlying principles, see code‑level examples, and walk away with a ready‑to‑use checklist that keeps your site safe and your SEO rankings high.

Understanding CSRF and Its Risks

What is CSRF?

CSRF exploits the trust that a web browser has in a logged‑in user. An attacker tricks the victim’s browser into sending a state‑changing request (such as POST /transfer) to a target site where the user is already authenticated. Because the browser automatically includes cookies, the request appears legitimate, and the server processes it as if the user had initiated the action.

Real‑world impact

• Financial loss: Unauthorized fund transfers, subscription cancellations, or purchase orders.
• Data integrity: Deleting or modifying user records, changing passwords, or altering settings.
• Reputation damage: Users lose trust when their accounts are compromised, which can hurt search rankings and organic traffic.

Core Principles of CSRF Protection

• Synchronizer token pattern: Generate a unique, unpredictable token per user session and require it on every state‑changing request.
• SameSite cookie attribute: Instruct browsers not to send cookies on cross‑origin requests (e.g., SameSite=Lax or Strict).
• Double‑submit cookie: Send the token both as a cookie and as a request parameter, then compare them on the server.
• Origin/Referer validation: Verify that the Origin or Referer header matches your domain for non‑GET requests.

When these principles are combined, an attacker’s forged request will lack a valid token or will be blocked by the browser, effectively neutralizing the threat.

Implementing CSRF Protection in Popular Python Frameworks

Django – Built‑in CSRF Middleware

Django ships with a mature CSRF system that works out of the box. The CsrfViewMiddleware validates tokens for any POST, PUT, PATCH, or DELETE request.

# settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',  # ← enabled by default
    # …
]

# template.html
<form method="post" action="/submit/">
    {% csrf_token %}
    <input type="text" name="name">
    <button type="submit">Send</button>
</form>

The {% csrf_token %} tag injects a hidden input containing the session‑specific token. Django also sets a csrftoken cookie, enabling the double‑submit pattern for AJAX calls:

fetch('/api/data/', {
    method: 'POST',
    headers: {
        'X-CSRFToken': getCookie('csrftoken'),  // custom helper
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({key: 'value'})
});

Flask – Using Flask‑WTF or Manual Tokens

Flask does not include CSRF protection by default, but the Flask‑WTF extension adds a seamless layer.

# app.py
from flask import Flask, render_template, request
from flask_wtf import CSRFProtect

app = Flask(__name__)
app.config['SECRET_KEY'] = 'a-very-secret-key'
csrf = CSRFProtect(app)   # ← activates protection for all POST routes

@app.route('/login', methods=['GET', 'POST'])
def login():
    if request.method == 'POST':
        # process login
        pass
    return render_template('login.html')

In your Jinja2 template, include the token with {{ csrf_token() }}:

<form method="post" action="{{ url_for('login') }}">
    <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
    <input type="text" name="username">
    <input type="password" name="password">
    <button type="submit">Log In</button>
</form>

If you prefer a lightweight approach, you can generate and verify tokens manually:

import secrets
from flask import session, abort, request

def generate_csrf_token():
    token = secrets.token_urlsafe(32)
    session['csrf_token'] = token
    return token

def validate_csrf():
    token = session.get('csrf_token')
    header = request.headers.get('X-CSRFToken') or request.form.get('csrf_token')
    if not token or token != header:
        abort(400, 'Invalid CSRF token')

FastAPI – Middleware for Token Validation

FastAPI, built on Starlette, encourages explicit security layers. Below is a minimal CSRF middleware that checks a token stored in a signed cookie.

# csrf_middleware.py
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import Response
from itsdangerous import URLSafeSerializer, BadSignature
import os

serializer = URLSafeSerializer(os.getenv('SECRET_KEY', 'fallback-secret'))

class CSRFMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # Only protect unsafe methods
        if request.method not in ('GET', 'HEAD', 'OPTIONS'):
            cookie = request.cookies.get('csrf_token')
            header = request.headers.get('X-CSRF-Token')
            if not cookie or not header:
                return Response('CSRF token missing', status_code=400)
            try:
                token = serializer.loads(cookie)
                if token != header:
                    raise ValueError('Token mismatch')
            except (BadSignature, ValueError):
                return Response('Invalid CSRF token', status_code=400)
        response = await call_next(request)
        # Set token for safe methods
        if request.method == 'GET' and 'csrf_token' not in request.cookies:
            token = serializer.dumps(secrets.token_urlsafe(32))
            response.set_cookie('csrf_token', token, httponly=False, samesite='Lax')
        return response

# main.py
from fastapi import FastAPI, Request
from csrf_middleware import CSRFMiddleware

app = FastAPI()
app.add_middleware(CSRFMiddleware)

@app.post('/comment')
async def add_comment(request: Request):
    data = await request.json()
    # process comment
    return {'status': 'saved'}

Clients send the token via the X-CSRF-Token header, which the middleware validates against the signed cookie.

Manual CSRF Token Management (When Framework Support Is Not Enough)

Sometimes you need a custom solution—perhaps for a microservice that only serves JSON APIs. Follow these steps:

1. Generate a cryptographically strong token. Use secrets.token_urlsafe() and store it in the user’s session or a signed cookie.
2. Expose the token to the client. Render it in HTML, return it in a JSON payload, or set it as a cookie with SameSite=Lax.
3. Require the token on every state‑changing request. Accept it via a custom header (e.g., X-CSRF-Token) or a hidden form field.
4. Validate the token server‑side. Compare the received value with the stored one; reject the request with 400 Bad Request on mismatch.
5. Rotate the token periodically. Regenerate after login, logout, or every few hours to limit exposure.

Common Pitfalls and How to Avoid Them

• Disabling CSRF for JSON endpoints. Never blanket‑disable protection; instead, enforce token checks on application/json requests just like form posts.
• Storing tokens in insecure cookies. Mark CSRF cookies as HttpOnly=False (so JavaScript can read them) but always set Secure and SameSite=Lax in production.
• Relying solely on