Auth Patterns

Authentication Patterns

Implement secure authentication with OAuth 2.1, Passkeys, and modern security standards.

Overview

• Login/signup flows
• JWT token management
• Session security
• OAuth 2.1 with PKCE
• Passkeys/WebAuthn
• Multi-factor authentication
• Role-based access control

Quick Reference

Password Hashing (Argon2id)

from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)
ph.verify(password_hash, password)

JWT Access Token

import jwt
from datetime import datetime, timedelta, timezone
payload = {
    'user_id': user_id,
    'type': 'access',
    'exp': datetime.now(timezone.utc) + timedelta(minutes=15),
}
token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')

OAuth 2.1 with PKCE (Required)

import hashlib, base64, secrets
code_verifier = secrets.token_urlsafe(64)
digest = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b'=').decode()

Session Security

app.config['SESSION_COOKIE_SECURE'] = True      # HTTPS only
app.config['SESSION_COOKIE_HTTPONLY'] = True    # No JS access
app.config['SESSION_COOKIE_SAMESITE'] = 'Strict'

Token Expiry ( Guidelines)

Anti-Patterns (FORBIDDEN)

# ❌ NEVER store passwords in plaintext
user.password = request.form['password']

# ❌ NEVER use implicit OAuth grant
response_type=token  # Deprecated in OAuth 2.1

# ❌ NEVER skip rate limiting on login
@app.route('/login')  # No rate limit!

# ❌ NEVER reveal if email exists
return "Email not found"  # Information disclosure

# ✅ ALWAYS use Argon2id or bcrypt
password_hash = ph.hash(password)

# ✅ ALWAYS use PKCE
code_challenge=challenge&code_challenge_method=S256

# ✅ ALWAYS rate limit auth endpoints
@limiter.limit("5 per minute")

# ✅ ALWAYS use generic error messages
return "Invalid credentials"

Key Decisions

Detailed Documentation

Related Skills

• owasp-top-10 - Security fundamentals
• input-validation - Data validation
• api-design-framework - API security

Capability Details

password-hashing

Keywords: password, hashing, bcrypt, argon2, hash Solves:

• Securely hash passwords with modern algorithms
• Configure appropriate cost factors
• Migrate legacy password hashes

jwt-tokens

Keywords: JWT, token, access token, claims, jsonwebtoken Solves:

• Generate and validate JWT access tokens
• Implement proper token expiration
• Handle token refresh securely

oauth2-pkce

Keywords: OAuth, PKCE, OAuth 2.1, authorization code, code verifier Solves:

• Implement OAuth 2.1 with PKCE flow
• Secure authorization for SPAs and mobile apps
• Handle OAuth provider integration

passkeys-webauthn

Keywords: passkey, WebAuthn, FIDO2, passwordless, biometric Solves:

• Implement passwordless authentication
• Configure WebAuthn registration and login
• Support cross-device passkeys

session-management

Keywords: session, cookie, session storage, logout, invalidate Solves:

• Manage user sessions securely
• Implement session invalidation on logout
• Handle concurrent sessions

role-based-access

Keywords: RBAC, role, permission, authorization, access control Solves:

• Implement role-based access control
• Define permission hierarchies
• Check authorization in routes

Authentication Security Checklist

Password Security

• [ ] Use Argon2id (preferred) or bcrypt for hashing
• [ ] Minimum 12 character password requirement
• [ ] Check against common password lists
• [ ] No password hints or security questions
• [ ] Rate limit password attempts (5 per minute)
• [ ] Account lockout after 10 failed attempts

Token Security

• [ ] Access tokens: 15 min - 1 hour lifetime
• [ ] Refresh tokens: 7-30 days with rotation
• [ ] Store access tokens in memory only (not localStorage)
• [ ] Store refresh tokens in HTTPOnly cookies
• [ ] Implement refresh token rotation
• [ ] Revoke all tokens on password change

Session Security

• [ ] SESSION_COOKIE_SECURE=True (HTTPS only)
• [ ] SESSION_COOKIE_HTTPONLY=True (no JS access)
• [ ] SESSION_COOKIE_SAMESITE='Strict'
• [ ] Session timeout (1 hour inactivity)
• [ ] Regenerate session ID on login

OAuth 2.1 Compliance

• [ ] Use PKCE for ALL clients
• [ ] No implicit grant
• [ ] No password grant
• [ ] State parameter for CSRF protection
• [ ] Validate redirect_uri exactly
• [ ] Use HTTPS for all endpoints

Passkeys/WebAuthn (If Implemented)

• [ ] Require user verification (biometric)
• [ ] Require resident keys for passwordless
• [ ] Validate RP ID matches origin
• [ ] Track sign count for replay protection
• [ ] Allow multiple passkeys per user

Multi-Factor Authentication

• [ ] Offer MFA (TOTP, Passkeys)
• [ ] TOTP: 6 digits, 30-second window
• [ ] Backup codes (10 one-time use)
• [ ] Remember device option (30 days max)
• [ ] Require MFA for sensitive operations

Rate Limiting

Error Messages

• [ ] Generic "Invalid credentials" (don't reveal which is wrong)
• [ ] Don't reveal if email exists in forgot password
• [ ] Log detailed errors server-side only
• [ ] No stack traces in production

Secure Headers

response.headers['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains'
response.headers['X-Content-Type-Options'] = 'nosniff'
response.headers['X-Frame-Options'] = 'DENY'
response.headers['Content-Security-Policy'] = "default-src 'self'"

Audit Logging

• [ ] Log all authentication attempts
• [ ] Log password changes
• [ ] Log MFA setup/disable
• [ ] Log token revocations
• [ ] Log suspicious activity (multiple failed attempts)

Review Checklist

Before deployment:

• [ ] No hardcoded secrets in code
• [ ] Secrets in environment variables
• [ ] HTTPS enforced everywhere
• [ ] Rate limiting configured
• [ ] Audit logging enabled
• [ ] Password hashing uses Argon2id or bcrypt
• [ ] Token lifetimes appropriate
• [ ] MFA available

Common Vulnerabilities to Avoid

• [ ] No password in URL parameters
• [ ] No session ID in URL
• [ ] No sensitive data in JWT payload
• [ ] No implicit OAuth grant
• [ ] No predictable session IDs
• [ ] No client-side token storage in localStorage

Authentication Implementation Examples

Password Hashing (Argon2id)

from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError

ph = PasswordHasher(
    time_cost=3,        # Number of iterations
    memory_cost=65536,  # 64 MB
    parallelism=4,      # Number of threads
)

def hash_password(password: str) -> str:
    """Hash password with Argon2id."""
    return ph.hash(password)

def verify_password(password_hash: str, password: str) -> bool:
    """Verify password against hash."""
    try:
        ph.verify(password_hash, password)
        return True
    except VerifyMismatchError:
        return False

# Check if rehash needed (parameters changed)
def needs_rehash(password_hash: str) -> bool:
    return ph.check_needs_rehash(password_hash)

JWT Access Token

import jwt
from datetime import datetime, timedelta, timezone

SECRET_KEY = os.environ["JWT_SECRET_KEY"]
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 15

def create_access_token(user_id: str, roles: list[str] = None) -> str:
    """Create short-lived access token."""
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "type": "access",
        "roles": roles or [],
        "iat": now,
        "exp": now + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

def verify_access_token(token: str) -> dict | None:
    """Verify and decode access token."""
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        if payload.get("type") != "access":
            return None
        return payload
    except jwt.ExpiredSignatureError:
        return None
    except jwt.InvalidTokenError:
        return None

Session Management

from flask import Flask, session
from datetime import datetime, timedelta, timezone

app = Flask(__name__)

# Secure session configuration
app.config.update(
    SECRET_KEY=os.environ["SESSION_SECRET"],
    SESSION_COOKIE_SECURE=True,       # HTTPS only
    SESSION_COOKIE_HTTPONLY=True,     # No JavaScript access
    SESSION_COOKIE_SAMESITE='Strict', # CSRF protection
    PERMANENT_SESSION_LIFETIME=timedelta(hours=1),
)

@app.route('/login', methods=['POST'])
def login():
    user = authenticate(request.form['email'], request.form['password'])
    if user:
        session.permanent = True
        session['user_id'] = user.id
        session['created_at'] = datetime.now(timezone.utc).isoformat()
        return redirect('/dashboard')
    return render_template('login.html', error='Invalid credentials')

@app.route('/logout', methods=['POST'])
def logout():
    session.clear()
    return redirect('/login')

Rate Limiting

from flask_limiter import Limiter
from flask_limiter.util import get_remote_address

limiter = Limiter(
    app,
    key_func=get_remote_address,
    default_limits=["200 per day", "50 per hour"],
    storage_uri="redis://localhost:6379",
)

@app.route('/api/auth/login', methods=['POST'])
@limiter.limit("5 per minute")  # Strict rate limit for login
def login():
    # Login logic
    pass

@app.route('/api/auth/password-reset', methods=['POST'])
@limiter.limit("3 per hour")  # Very strict for password reset
def password_reset():
    # Always return success (don't reveal if email exists)
    return {"message": "If email exists, reset link sent"}

Role-Based Access Control

from functools import wraps
from flask import abort, g

def require_role(*roles):
    """Decorator to require specific role(s)."""
    def decorator(f):
        @wraps(f)
        def wrapper(*args, **kwargs):
            if not g.current_user:
                abort(401)
            if not any(role in g.current_user.roles for role in roles):
                abort(403)
            return f(*args, **kwargs)
        return wrapper
    return decorator

def require_permission(permission: str):
    """Decorator to require specific permission."""
    def decorator(f):
        @wraps(f)
        def wrapper(*args, **kwargs):
            if not g.current_user:
                abort(401)
            if not g.current_user.has_permission(permission):
                abort(403)
            return f(*args, **kwargs)
        return wrapper
    return decorator

# Usage
@app.route('/admin/users')
@require_role('admin')
def admin_users():
    return get_all_users()

@app.route('/api/patients/<id>')
@require_permission('patients:read')
def get_patient(id):
    return get_patient_by_id(id)

Multi-Factor Authentication (TOTP)

import pyotp
import qrcode
from io import BytesIO
import base64

def generate_totp_secret() -> str:
    """Generate new TOTP secret for user."""
    return pyotp.random_base32()

def get_totp_provisioning_uri(secret: str, email: str, issuer: str = "MyApp") -> str:
    """Get provisioning URI for authenticator app."""
    totp = pyotp.TOTP(secret)
    return totp.provisioning_uri(name=email, issuer_name=issuer)

def get_totp_qr_code(provisioning_uri: str) -> str:
    """Generate QR code as base64 image."""
    qr = qrcode.QRCode(version=1, box_size=10, border=5)
    qr.add_data(provisioning_uri)
    qr.make(fit=True)
    
    img = qr.make_image(fill_color="black", back_color="white")
    buffer = BytesIO()
    img.save(buffer, format="PNG")
    
    return base64.b64encode(buffer.getvalue()).decode()

def verify_totp(secret: str, code: str) -> bool:
    """Verify TOTP code."""
    totp = pyotp.TOTP(secret)
    return totp.verify(code, valid_window=1)  # Allow 1 period window

# Usage
@app.route('/api/auth/mfa/setup', methods=['POST'])
@login_required
def setup_mfa():
    secret = generate_totp_secret()
    uri = get_totp_provisioning_uri(secret, g.current_user.email)
    qr = get_totp_qr_code(uri)
    
    # Store secret temporarily until verified
    session['pending_mfa_secret'] = secret
    
    return {"qr_code": qr, "secret": secret}

@app.route('/api/auth/mfa/verify', methods=['POST'])
@login_required
def verify_mfa_setup():
    code = request.json['code']
    secret = session.get('pending_mfa_secret')
    
    if verify_totp(secret, code):
        g.current_user.mfa_secret = secret
        g.current_user.mfa_enabled = True
        db.session.commit()
        return {"success": True}
    
    return {"error": "Invalid code"}, 400

Complete Login Flow with MFA

@app.route('/api/auth/login', methods=['POST'])
@limiter.limit("5 per minute")
def login():
    email = request.json.get('email')
    password = request.json.get('password')
    
    user = User.query.filter_by(email=email).first()
    
    # Don't reveal if user exists
    if not user or not verify_password(user.password_hash, password):
        return {"error": "Invalid credentials"}, 401
    
    # Check if MFA required
    if user.mfa_enabled:
        # Create temporary token for MFA step
        mfa_token = create_mfa_pending_token(user.id)
        return {"mfa_required": True, "mfa_token": mfa_token}
    
    # No MFA - issue tokens
    return issue_tokens(user)

@app.route('/api/auth/mfa', methods=['POST'])
@limiter.limit("5 per minute")
def verify_mfa():
    mfa_token = request.json.get('mfa_token')
    code = request.json.get('code')
    
    # Verify MFA pending token
    user_id = verify_mfa_pending_token(mfa_token)
    if not user_id:
        return {"error": "Invalid or expired MFA token"}, 401
    
    user = User.query.get(user_id)
    
    # Verify TOTP code
    if not verify_totp(user.mfa_secret, code):
        return {"error": "Invalid MFA code"}, 401
    
    return issue_tokens(user)

def issue_tokens(user):
    """Issue access and refresh tokens."""
    access_token = create_access_token(user.id, user.roles)
    refresh_token = create_refresh_token(user.id)
    
    return {
        "access_token": access_token,
        "refresh_token": refresh_token,
        "token_type": "Bearer",
        "expires_in": ACCESS_TOKEN_EXPIRE_MINUTES * 60,
    }

OAuth 2.1 & Passkeys Reference

OAuth 2.1 Overview

OAuth 2.1 consolidates OAuth 2.0 best practices and security requirements:

Key Changes from OAuth 2.0

• PKCE required for ALL clients (not just public)
• Implicit grant removed (security vulnerability)
• Password grant removed (credential anti-pattern)
• Bearer tokens must use TLS
• Refresh token rotation mandatory

PKCE Flow (Required)

import hashlib
import base64
import secrets

def generate_pkce_pair():
    """Generate code_verifier and code_challenge for PKCE."""
    # Generate random code_verifier (43-128 chars)
    code_verifier = secrets.token_urlsafe(64)
    
    # Create code_challenge using S256
    digest = hashlib.sha256(code_verifier.encode()).digest()
    code_challenge = base64.urlsafe_b64encode(digest).rstrip(b'=').decode()
    
    return code_verifier, code_challenge

# Usage
verifier, challenge = generate_pkce_pair()

# Step 1: Authorization request
auth_url = f"""https://auth.example.com/authorize?
    response_type=code
    &client_id={client_id}
    &redirect_uri={redirect_uri}
    &code_challenge={challenge}
    &code_challenge_method=S256
    &state={state}
    &scope=openid profile"""

# Step 2: Exchange code for tokens
token_response = requests.post(
    "https://auth.example.com/token",
    data={
        "grant_type": "authorization_code",
        "code": auth_code,
        "redirect_uri": redirect_uri,
        "client_id": client_id,
        "code_verifier": verifier,  # PKCE verification
    }
)

Token Lifetimes (2026 Recommendations)

DPoP (Demonstrating Proof of Possession)

Binds tokens to client cryptographic keys:

import jwt
import time
import uuid

def create_dpop_proof(http_method: str, http_uri: str, private_key) -> str:
    """Create DPoP proof for request."""
    claims = {
        "jti": str(uuid.uuid4()),
        "htm": http_method,
        "htu": http_uri,
        "iat": int(time.time()),
    }
    
    headers = {
        "typ": "dpop+jwt",
        "alg": "ES256",
        "jwk": private_key.public_key().export_key(),
    }
    
    return jwt.encode(claims, private_key, algorithm="ES256", headers=headers)

# Usage
dpop_proof = create_dpop_proof("POST", "https://api.example.com/token", private_key)

response = requests.post(
    "https://api.example.com/token",
    headers={"DPoP": dpop_proof},
    data={"grant_type": "refresh_token", "refresh_token": rt},
)

Passkeys / WebAuthn

Overview

Passkeys replace passwords with cryptographic credentials:

• Phishing-resistant: Bound to origin
• Passwordless: No secrets to remember
• Multi-device: Synced via platform
• Biometric: Face ID, Touch ID, fingerprint

Registration Flow

from webauthn import (
    generate_registration_options,
    verify_registration_response,
)
from webauthn.helpers.structs import (
    AuthenticatorSelectionCriteria,
    ResidentKeyRequirement,
    UserVerificationRequirement,
)

# Step 1: Generate registration options
options = generate_registration_options(
    rp_id="example.com",
    rp_name="Example App",
    user_id=user.id.encode(),
    user_name=user.email,
    user_display_name=user.name,
    authenticator_selection=AuthenticatorSelectionCriteria(
        resident_key=ResidentKeyRequirement.REQUIRED,
        user_verification=UserVerificationRequirement.REQUIRED,
    ),
)

# Send options to client
return jsonify(options)

# Step 2: Verify registration response
verification = verify_registration_response(
    credential=client_response,
    expected_challenge=stored_challenge,
    expected_rp_id="example.com",
    expected_origin="https://example.com",
)

# Store credential
db.save_credential(
    user_id=user.id,
    credential_id=verification.credential_id,
    public_key=verification.credential_public_key,
    sign_count=verification.sign_count,
)

Authentication Flow

from webauthn import (
    generate_authentication_options,
    verify_authentication_response,
)

# Step 1: Generate authentication options
options = generate_authentication_options(
    rp_id="example.com",
    allow_credentials=[
        {"id": cred.credential_id, "type": "public-key"}
        for cred in user.credentials
    ],
)

# Step 2: Verify authentication response
verification = verify_authentication_response(
    credential=client_response,
    expected_challenge=stored_challenge,
    expected_rp_id="example.com",
    expected_origin="https://example.com",
    credential_public_key=stored_credential.public_key,
    credential_current_sign_count=stored_credential.sign_count,
)

# Update sign count (replay protection)
stored_credential.sign_count = verification.new_sign_count
db.save(stored_credential)

# Issue session/tokens
return create_session(user)

Frontend Implementation

// Registration
async function registerPasskey(options: PublicKeyCredentialCreationOptions) {
  const credential = await navigator.credentials.create({
    publicKey: options,
  });
  
  // Send credential to server
  await fetch('/api/auth/passkey/register', {
    method: 'POST',
    body: JSON.stringify(credential),
  });
}

// Authentication
async function authenticateWithPasskey(options: PublicKeyCredentialRequestOptions) {
  const credential = await navigator.credentials.get({
    publicKey: options,
  });
  
  // Send credential to server
  const response = await fetch('/api/auth/passkey/authenticate', {
    method: 'POST',
    body: JSON.stringify(credential),
  });
  
  return response.json();
}

// Conditional UI (autofill)
if (window.PublicKeyCredential?.isConditionalMediationAvailable) {
  const available = await PublicKeyCredential.isConditionalMediationAvailable();
  if (available) {
    // Show passkey autofill in username field
    const credential = await navigator.credentials.get({
      publicKey: options,
      mediation: 'conditional',
    });
  }
}

Refresh Token Rotation

import secrets
import hashlib
from datetime import datetime, timedelta, timezone

def rotate_refresh_token(old_token: str, db) -> tuple[str, str]:
    """Rotate refresh token on use (security best practice)."""
    old_hash = hashlib.sha256(old_token.encode()).hexdigest()
    
    # Find and validate old token
    token_record = db.query("""
        SELECT user_id, version FROM refresh_tokens
        WHERE token_hash = ? AND expires_at > NOW() AND revoked = FALSE
    """, [old_hash]).fetchone()
    
    if not token_record:
        raise InvalidTokenError("Refresh token invalid or expired")
    
    user_id, version = token_record
    
    # Revoke old token
    db.execute(
        "UPDATE refresh_tokens SET revoked = TRUE WHERE token_hash = ?",
        [old_hash]
    )
    
    # Create new tokens
    new_access_token = create_access_token(user_id)
    
    new_refresh_token = secrets.token_urlsafe(32)
    new_hash = hashlib.sha256(new_refresh_token.encode()).hexdigest()
    
    db.execute("""
        INSERT INTO refresh_tokens (user_id, token_hash, expires_at, version)
        VALUES (?, ?, ?, ?)
    """, [user_id, new_hash, datetime.now(timezone.utc) + timedelta(days=7), version + 1])
    
    return new_access_token, new_refresh_token

External Links

• OAuth 2.1 Draft Spec
• WebAuthn Spec
• FIDO Alliance
• py_webauthn Library