auth-system-design

MUmerRazzaq's avatarfrom MUmerRazzaq

Authentication system design and implementation guidance with Python examples using strict typing. Use when: (1) Designing authentication flows (signup, login, logout, refresh), (2) Selecting between session vs token-based auth, (3) Designing JWT structure and claims, (4) Implementing OAuth 2.0 flows, (5) Setting up multi-service authentication patterns, (6) Creating password reset and email verification flows, (7) Implementing role-based access control (RBAC), (8) Creating security checklists for auth systems, (9) Planning frontend/backend auth integration. All examples follow Python typing standards and security best practices.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 25, 2025⬇️1downloads
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides comprehensive guidance on designing and implementing secure, scalable authentication systems. It offers expert-level support for selecting authentication methods, defining JWT structures, and implementing OAuth 2.0 flows. By providing production-ready Python examples with strict typing and security best practices, it helps developers build robust identity management systems that prevent common vulnerabilities.

Use Cases

  • Designing end-to-end authentication flows for new web applications, including secure signup, login, and multi-factor verification.
  • Implementing stateless authentication for microservices or SPAs using JWT tokens with industry-standard claims and RS256 encryption.
  • Integrating third-party social logins and identity providers using standardized OAuth 2.0 and OpenID Connect protocols.
  • Developing granular Role-Based Access Control (RBAC) systems to manage complex user permissions and resource security.
  • Auditing and hardening existing authentication infrastructures using comprehensive security checklists and best-practice validation patterns.
nameauth-system-design
description|
Authentication system design and implementation guidance with Python examples using strict typing. Use when(1) Designing authentication flows (signup, login, logout, refresh), (2) Selecting between session vs token-based auth, (3) Designing JWT structure and claims, (4) Implementing OAuth 2.0 flows, (5) Setting up multi-service authentication patterns, (6) Creating password reset and email verification flows, (7) Implementing role-based access control (RBAC), (8) Creating security checklists for auth systems, (9) Planning frontend/backend auth integration. All examples follow Python typing standards and security best practices.

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