Authentication System Design

Design secure and scalable authentication systems following industry best practices and security standards.

Quick Reference

Authentication Method Selection

• Session-based: Traditional web apps, server-side control
• JWT Token: SPA/mobile/microservices, stateless
• OAuth 2.0: Third-party integration, standard protocols
• OpenID Connect: Identity + authentication

JWT Claims Structure

• Standard: iss, sub, aud, exp, nbf, iat, jti
• Custom: userId, roles, permissions

Decision Workflow

1. Choose Authentication Method

| Method | Best For | Key Considerations | |--------|----------|-------------------| | Session-based | Traditional web apps | Server state required | | JWT Token | SPA, mobile, microservices | Token revocation challenges | | OAuth 2.0 | Third-party integration | Complex setup | | OpenID Connect | Identity verification | More complex than OAuth |

2. Design Authentication Flows

• Sign Up: Validate → Create → Verify → Login
• Login: Validate → Generate tokens → Redirect
• Logout: Invalidate → Clear → Redirect
• Refresh: Check expiry → Use refresh token → Retry

3. JWT Structure & OAuth Selection

• Use RS256 algorithm, short expiry (15-60 min)
• Authorization Code flow for web apps, PKCE for public clients

4. Security Validation

• Password hashing (bcrypt/Argon2)
• Rate limiting, HTTPS, token expiration
• Input validation, secure headers

Essential Patterns

Secure Password Handling

import bcrypt
def hash_password(password: str) -> str:
    salt = bcrypt.gensalt(rounds=12)
    return bcrypt.hashpw(password.encode(), salt).decode()

def verify_password(plain: str, hashed: str) -> bool:
    return bcrypt.checkpw(plain.encode(), hashed.encode())

JWT Token Operations

import jwt
from datetime import datetime, timedelta

def create_token(user_id: str, roles: list) -> str:
    payload = {
        "user_id": user_id,
        "roles": roles,
        "exp": (datetime.utcnow() + timedelta(minutes=15)).timestamp(),
        "iss": "https://your-app.com"
    }
    return jwt.encode(payload, key="secret", algorithm="RS256")

Resources

| File | Purpose | |------|---------| | auth-methods.md | Authentication method comparison | | auth-flows.md | Flow diagrams and implementation | | jwt-structure.md | JWT guidelines and examples | | oauth-flows.md | OAuth 2.0 patterns | | multi-service-auth.md | Multi-service strategies | | password-reset.md | Secure reset implementation | | rbac-system.md | Role-based access control | | security-checklist.md | Security validation | | integration-guide.md | Frontend/backend integration | | jwt-template.yaml | JWT schema template |