securing-authentication

What this skill does

# 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)

```json
{
  "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 permissions       │
│                                                             │
│  Kubernetes / Infrastructure Policies                       │
│  └─ OPA (Gatekeeper for admission control)                 │
│      Example: Enforce pod security policies                │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

For detailed comparison, see `references/authorization-patterns.md`.

## Library Selection by Language

### TypeScript

| Use Case | Library | Context7 ID | Trust | Notes |
|----------|---------|-------------|-------|-------|
| Auth Framework | Auth.js v5 | `/websites/authjs_dev` | 87.4 | Multi-framework (Next, Svelte, Solid) |
| JWT | jose 5.x | - | - | EdDSA, ES256, RS256 support |
| Passkeys | @simplewebauthn/server 11.x | - | - | FIDO2 server |
| Validation | Zod 3.x | `/colinhacks/zod` | 90.4 | Schema validation |
| Policy Engine | Casbin.js 1.x | - | - | RBAC/ABAC embedded |

### Python

| Use Case | Library | Notes |
|----------|---------|-------|
| Auth Framework | Authlib 1.3+ | OAuth/OIDC client + server |
| JWT | joserfc 1.x | Modern, maintained |
| Passkeys | py_webauthn 2.x | WebAuthn server |
| Password Hashing | argon2-cffi 24.x | OWASP parameters |
| Validation | Pydantic 2.x | FastAPI integration |
| Policy Engine | PyCasbin 1.x | RBAC/ABAC embedded |

### Rust

| Use Case | Library | Notes |
|----------|---------|-------|
| JWT | jsonwebtoken 10.x | EdDSA, ES256, RS256 |
| OAuth Client | oauth2 5.x | OAuth 2.1 flows |
| Passkeys | webauthn-rs 0.5.x | WebAuthn + attestation |
| Password Hashing | argon2 0.5.x | Native Argon2id |
| Policy Engine | Casbin-RS 2.x | RBAC/ABAC embedded |

### Go

| Use Case | Library | Notes |
|----------|---------|-------|
| JWT | golang-jwt v5 | Community-maintained |
| OAuth Client | go-oidc v3 | OIDC client only |
| Passkeys | go-webauthn 0.11.x | Duo-maintained |
| Password Hashing | golang.org/x/crypto/argon2 | Standard library |
| Policy Engine | Casbin v2 | Original implementation |

## Managed Auth Services

| Service | Best For | Key Features |
|---------|----------|--------------|
| Clerk | Rapid development, startups | Prebuilt UI, Next.js SDK |
| Auth0 | Enterprise, established | 25+ social providers, SSO |
| WorkOS AuthKit | B2B SaaS, enterprise SSO | SAML/SCIM, admin portal |
| Supabase Auth | Postgres users