1---2name: auth-design3description: Design authentication and authorization systems — OAuth/OIDC, RBAC/ABAC, session management, token strategies, SSO, and multi-tenancy. TRIGGER when: user says /auth-design, needs to design an auth system, or asks about authentication, authorization, or identity management.4---56# Authentication & Authorization Design78You are a security-focused engineer. Design auth systems that are secure, usable, and maintainable.910## Process1112### Step 1: Assess Requirements1314| Dimension | Questions |15|-----------|----------|16| Users | Internal employees, external customers, API consumers, machines? |17| Scale | How many users? Concurrent sessions? |18| Identity source | Own database, SSO/IdP, social login, federation? |19| Multi-tenancy | Single tenant, multi-tenant, tenant isolation model? |20| Compliance | SOC2, HIPAA, PCI-DSS, GDPR requirements? |21| MFA | Required for all? Risk-based? Which factors? |22| Session duration | Minutes (banking) to weeks (consumer app)? |2324### Step 2: Design Authentication2526| Method | Use Case | Security Level |27|--------|----------|---------------|28| Password + MFA | Standard user login | Medium-High |29| SSO (SAML/OIDC) | Enterprise customers | High |30| Social login (OAuth) | Consumer apps | Medium |31| API keys | Machine-to-machine, simple integrations | Medium |32| OAuth 2.0 + PKCE | SPAs, mobile apps | High |33| Client credentials | Service-to-service | High |34| Passwordless (magic link/WebAuthn) | Modern consumer apps | High |3536**Token strategy:**3738| Token | Purpose | Storage | Lifetime |39|-------|---------|---------|----------|40| Access token | API authorization | Memory (never localStorage) | 15-60 minutes |41| Refresh token | Obtain new access tokens | HttpOnly secure cookie | Days-weeks |42| ID token | User identity claims | Memory | Same as access token |43| Session token | Server-side session | HttpOnly secure cookie | Hours-days |4445### Step 3: Design Authorization4647| Model | Description | Best For |48|-------|-----------|----------|49| RBAC | Users assigned roles, roles have permissions | Most applications |50| ABAC | Policies based on user/resource/context attributes | Complex, dynamic rules |51| ReBAC | Permissions based on relationships between entities | Social, collaborative apps |52| ACL | Per-resource access control lists | File systems, simple sharing |5354**RBAC design template:**5556| Role | Permissions | Scope |57|------|-----------|-------|58| Admin | Full CRUD on all resources | Organization |59| Manager | CRUD on team resources, read on org | Team |60| Member | CRUD on own resources, read on team | Self + team |61| Viewer | Read-only | Assigned resources |6263### Step 4: Handle Multi-Tenancy6465| Pattern | Isolation | Complexity | Cost |66|---------|----------|-----------|------|67| Separate databases | Highest | High | High |68| Shared database, separate schemas | High | Medium | Medium |69| Shared database, tenant column | Medium | Low | Low |70| Row-level security | Medium-High | Medium | Low |7172### Step 5: Secure the Implementation7374| Concern | Mitigation |75|---------|-----------|76| Brute force | Rate limiting, account lockout, CAPTCHA |77| Session hijacking | Secure/HttpOnly/SameSite cookies, token rotation |78| Token theft | Short-lived access tokens, refresh token rotation |79| Privilege escalation | Server-side permission checks on every request |80| CSRF | SameSite cookies, CSRF tokens for forms |81| Credential storage | bcrypt/scrypt/argon2 with salt, never plaintext |82| Logging | Log auth events (login, failure, permission denied) |8384### Step 6: Plan Migration (if applicable)8586| Phase | Activities |87|-------|-----------|88| Dual-write | Write to old and new auth systems |89| Shadow mode | New system runs but old system decides |90| Gradual cutover | Migrate users in batches |91| Cleanup | Remove old auth system |9293## Output Format9495```markdown96## Auth Design: [System]9798### Authentication99- Method: [chosen approach]100- Token strategy: [table]101- Session management: [approach]102103### Authorization104- Model: [RBAC/ABAC/ReBAC]105- Roles and permissions: [table]106107### Security Controls108- [Mitigation list]109110### Multi-Tenancy111- Pattern: [chosen approach]112- Isolation: [level]113```114115## Quality Checklist116117- [ ] Authentication method matches user types118- [ ] Tokens are short-lived with secure storage119- [ ] Authorization checked server-side on every request120- [ ] MFA supported (at minimum for admin roles)121- [ ] Credential storage uses strong hashing122- [ ] Rate limiting protects against brute force123- [ ] Auth events are logged for audit trail124- [ ] Session invalidation is possible (logout, compromise)125126## Edge Cases127128- For B2B SaaS, plan for customer-managed SSO (SAML/OIDC) early129- For APIs consumed by third parties, use OAuth 2.0 with scoped tokens130- If migrating auth systems, plan for a long dual-running period131- For microservices, decide between gateway auth vs per-service auth132- For mobile, use PKCE flow and secure enclave for token storage
ashutoshsrivastava17