/securing-authentication

name: securing-authentication
description: Authentication, authorization, and API security implementation. Use when building user systems, protecting APIs, or implementing access control. Covers OAuth 2.1/OIDC, JWT patterns, sessions, Passkeys/WebAuthn, RBAC/ABAC/ReBAC, policy engines (OPA, Casbin, SpiceDB), managed auth (Clerk, Auth0), self-hosted (Keycloak, Ory), and API security best practices.

Authentication & Security

Implement modern authentication, authorization, and API security across Python, Rust, Go, and TypeScript.

When to Use This Skill

Use this skill when:

• Building user authentication systems (login, signup, SSO)
• Implementing authorization (roles, permissions, access control)
• Securing APIs (JWT validation, rate limiting)
• Adding passwordless auth (Passkeys/WebAuthn)
• Migrating from password-based to modern auth
• Integrating enterprise SSO (SAML, OIDC)
• Implementing fine-grained permissions (RBAC, ABAC, ReBAC)

OAuth 2.1 Mandatory Requirements (2025 Standard)

┌─────────────────────────────────────────────────────────────┐
│           OAuth 2.1 MANDATORY REQUIREMENTS                  │
│                   (RFC 9798 - 2025)                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ REQUIRED (Breaking Changes from OAuth 2.0)             │
│  ├─ PKCE (Proof Key for Code Exchange) MANDATORY           │
│  │   └─ S256 method (SHA-256), minimum entropy 43 chars   │
│  ├─ Exact redirect URI matching                            │
│  │   └─ No wildcard matching, no substring matching       │
│  ├─ Authorization code flow ONLY for public clients       │
│  │   └─ All other flows require confidential client       │
│  └─ TLS 1.2+ required for all endpoints                   │
│                                                             │
│  ❌ REMOVED (No Longer Supported)                          │
│  ├─ Implicit grant (security vulnerabilities)             │
│  ├─ Resource Owner Password Credentials grant              │
│  │   └─ Use OAuth 2.0 Device Flow (RFC 8628) instead      │
│  └─ Bearer token in query parameters                       │
│      └─ Must use Authorization header or POST body        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

**Critical:** PKCE is now mandatory for ALL OAuth flows, not just public clients.

JWT Best Practices

Signing Algorithms (Priority Order)

1. **EdDSA with Ed25519** (Recommended)

• Fastest performance
• Smallest signature size
• Modern cryptography

2. **ES256 (ECDSA with P-256)**

• Good performance
• Industry standard
• Wide compatibility

3. **RS256 (RSA)**

• Legacy compatibility
• Larger signatures
• Slower performance

**NEVER allow `alg: none` or algorithm switching attacks.**

Token Lifetimes (Concrete Values)

• **Access token:** 5-15 minutes
• **Refresh token:** 1-7 days with rotation
• **ID token:** Same as access token (5-15 minutes)

**Refresh token rotation:** Each refresh generates new access AND refresh tokens, invalidating the old refresh token.

Token Storage

• **Access token:** Memory only (never localStorage)
• **Refresh token:** HTTP-only cookie + SameSite=Strict
• **CSRF token:** Separate non-HTTP-only cookie
• **Never log tokens:** Redact in application logs

JWT Claims (Required)

{
  "iss": "https://auth.example.com",
  "sub": "user-id-123",
  "aud": "api.example.com",
  "exp": 1234567890,
  "iat": 1234567890,
  "jti": "unique-token-id",
  "scope": "read:profile write:data"
}

Password Hashing with Argon2id

OWASP 2025 Parameters

Algorithm: Argon2id
Memory cost (m): 64 MB (65536 KiB)
Time cost (t): 3 iterations
Parallelism (p): 4 threads
Salt length: 16 bytes (128 bits)
Target hash time: 150-250ms

Implementation

For concrete implementations, see `references/password-hashing.md`.

**Key Points:**

• Argon2id is hybrid: data-independent timing + memory-hard
• Tune memory cost to achieve 150-250ms on YOUR hardware
• Use timing-safe comparison for verification
• Migrate from bcrypt gradually (verify with old, rehash with new)

Passkeys / WebAuthn

Passkeys provide phishing-resistant, passwordless authentication using FIDO2/WebAuthn.

When to Use Passkeys

• User-facing applications prioritizing security
• Reducing password-related support burden
• Mobile-first applications (biometric auth)
• Applications requiring MFA without SMS

Cross-Device Passkey Sync

• **iCloud Keychain:** Apple ecosystem (iOS 16+, macOS 13+)
• **Google Password Manager:** Android, Chrome
• **1Password, Bitwarden:** Third-party password managers

For implementation guide, see `references/passkeys-webauthn.md`.

Authorization Models

┌─────────────────────────────────────────────────────────────┐
│                Authorization Model Selection                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Simple Roles (<20 roles)                                  │
│  └─ RBAC with Casbin (embedded, any language)              │
│      Example: Admin, User, Guest                           │
│                                                             │
│  Complex Attribute Rules                                    │
│  └─ ABAC with OPA or Cerbos                                │
│      Example: "Allow if user.clearance >= doc.level        │
│                AND user.dept == doc.dept"                   │
│                                                             │
│  Relationship-Based (Multi-Tenant, Collaborative)          │
│  └─ ReBAC with SpiceDB (Zanzibar model)                    │
│      Example: "Can edit if member of doc's workspace       │
│                AND workspace.plan includes feature"         │
│      Use cases: Notion-like, GitHub-like