OAuth State and CSRF Protection

Welcome to the lesson on OAuth state parameter & CSRF protection! In Units 2-3, we implemented a simplified OAuth flow to learn the basics. Now it's time to upgrade to production security.

🔒 Security Upgrade in This Unit:

We're making two critical improvements:

1. Adding CSRF Protection: The state parameter prevents attackers from hijacking OAuth flows
2. Switching to /callback Routes: Following OAuth standard naming (instead of /success)

This lesson transforms your OAuth implementation from "learning demo" to "production-ready security". Let's dive in! 🛡️

Cross-site request forgery (CSRF) attacks in OAuth occur when malicious websites trick users into completing OAuth flows they didn't intend to start. Without proper protection, an attacker could:

1. Start an OAuth flow with their own account (e.g., their Google account).
2. Obtain a valid authorization code from that flow.
3. Trick a victim into completing the callback with the attacker's authorization code.
4. Link the attacker's OAuth account to the victim's application session.

This allows the attacker to access the victim's session or causes the victim to unknowingly use the attacker's account. For example, if the victim uploads sensitive documents thinking they're using their own Google Drive integration, those documents end up in the attacker's Google Drive instead.

This is possible because OAuth callbacks typically accept any valid authorization code, regardless of who initiated the original request.

In Units 2-3, we used /success routes for simplicity. Now we're switching to the OAuth standard /callback pattern with state validation:

Before (Units 2-3 - Learning Demo):
/auth/google → /success

After (Unit 4+ - Secure):
/auth/google → /callback?code=xxx&state=yyy

The /callback route:

1. Receives an authorization code from the OAuth provider
2. Receives the state parameter we generated earlier
3. Validates the state for CSRF protection
4. Exchanges the code for user information
5. Generates a JWT and redirects to the home page

This is the OAuth 2.0 standard pattern used by Google, GitHub, and all major providers.

The state parameter acts as a unique identifier that proves the OAuth request is legitimate. Here's how it works:

1. Your app generates a random state value when starting OAuth.
2. The consent screen includes this state in the callback URL when the user authorizes.
3. Your app verifies the state matches before processing the request.

If the state doesn't match, you know the request didn't originate from your app.

Let's implement the state parameter to secure our OAuth flow. We'll generate a cryptographically secure state value and store it for later validation.

import secrets
import time

# Simple state storage for CSRF protection
oauth_states = {}

def generate_state():
    return secrets.token_hex(16)

@router.get("/google")
async def google_oauth_login():
    # Generate and store state
    state = generate_state()
    oauth_states[state] = {'provider': 'google', 'timestamp': time.time()}
    
    # Pass state to the consent screen template
    html = google_template.replace('{{STATE}}', state)
    return HTMLResponse(content=html)

Note: We use secrets.token_hex() instead of Python's random module because the state parameter must be cryptographically secure and unpredictable to prevent CSRF attacks. The random module is not suitable for security purposes.

The {{STATE}} placeholder in our HTML template gets replaced with the actual state value, which is then included in the callback URL when the user authorizes.

Next, we'll validate the state parameter when handling the OAuth callback. The callback also processes the authorization code, creates or retrieves the user, and generates a JWT token.

from fastapi import Query, Depends
from fastapi.responses import RedirectResponse
from sqlalchemy.ext.asyncio import AsyncSession
from jose import jwt
from datetime import datetime, timedelta

# State expiration time in seconds (10 minutes)
STATE_EXPIRATION = 600

@router.get("/google/callback")
async def google_oauth_callback(
    state: str = Query(None),
    code: str = Query(None),
    db: AsyncSession = Depends(get_db)
):
    # Verify state parameter exists
    if not state or state not in oauth_states:
        print(f'Invalid OAuth state: {state}')
        return RedirectResponse(url='/login?error=state_mismatch')
    
    # Validate state expiration (prevent replay attacks)
    state_data = oauth_states[state]
    if time.time() - state_data['timestamp'] > STATE_EXPIRATION:
        del oauth_states[state]
        print(f'Expired OAuth state: {state}')
        return RedirectResponse(url='/login?error=state_expired')
    
    # Remove used state to prevent replay attacks
    del oauth_states[state]
    
    try:
        # Create or retrieve user and generate token
        result = await db.execute(select(User).where(User.username == 'google_user'))
        user = result.scalar_one_or_none()
        
        if not user:
            user = User(
                username='google_user',
                password=None,
                provider='google'
            )
            db.add(user)
            await db.commit()
            await db.refresh(user)
        
        # Generate JWT with expiration
        token_data = {
            'userId': user.id,
            'exp': datetime.utcnow() + timedelta(hours=24)
        }
        token = jwt.encode(token_data, get_jwt_secret(), algorithm='HS256')
        
        return RedirectResponse(url=f'/?token={token}&provider=google')
    except Exception as error:
        print(f'Google OAuth error: {error}')
        return RedirectResponse(url='/login?error=oauth_error')

This validation ensures that only legitimate OAuth requests are processed, protecting against CSRF attacks. After validation, we delete the state to prevent replay attacks where someone might try to reuse the same authorization.

⚠️ Important: The in-memory dictionary approach shown above is for educational purposes only and has significant limitations in production environments:

• Not scalable: In a multi-instance deployment, each server has its own dictionary. A request initiated on one server cannot be validated on another, causing OAuth flows to fail randomly.
• Not persistent: All stored states are lost when the server restarts, invalidating any active OAuth flows.

For production applications, you should use a shared, persistent store such as:

• Redis for fast, distributed session storage.
• Database session table for persistent storage with your existing database.
• Other distributed caches that can be shared across server instances.

Example with Redis:

import json

# Production approach with Redis
redis_client.setex(
    f'oauth_state:{state}',
    600,  # 10 minute expiration
    json.dumps({'provider': 'google', 'timestamp': time.time()})
)

In this lesson, we learned how malicious websites can exploit OAuth flows without proper protection and how the state parameter prevents these attacks. We implemented state generation, storage, and validation to secure our OAuth callback endpoints for both Google and GitHub providers.

We also upgraded from simplified /success routes to standard /callback routes following OAuth 2.0 conventions.

The key takeaway: Always validate the state parameter before processing OAuth responses. This simple step prevents attackers from hijacking your OAuth flows.

In the next practice, you'll implement this security measure in your own OAuth system! 🚀