auth-engineer

# Auth Engineer ## Purpose Implement secure, scalable authentication and authorization systems. This skill covers identity protocols, token management, access control patterns, and the security considerations critical for production auth systems. ## Authentication vs Authorization ``` AUTHENTICATION (AuthN): "Who are you?" Verifying identity via credentials (password, token, certificate). AUTHORIZATION (AuthZ): "What can you do?" Determining permissions based on identity (role, attribute, policy). FLOW: 1. User authenticates (login) -> receives identity token 2. User makes request with token -> server authorizes the action 3. If authorized -> perform action 4. If not authorized -> 403 Forbidden ``` ## JWT Architecture ### JWT Structure ``` HEADER.PAYLOAD.SIGNATURE Header (algorithm + type): { "alg": "RS256", "typ": "JWT", "kid": "key-2025-01" } Payload (claims): { "sub": "user_abc123", // Subject (user ID) "iss": "[reference URL]", // Issuer "aud": "[reference URL]", // Audience "exp": 1705312800, // Expiration (Unix timestamp) "iat": 1705309200, // Issued at "nbf": 1705309200, // Not before "jti": "unique-token-id", // JWT ID (for revocation) "role": "admin", // Custom claims "permissions": ["read:users", "write:users"] } Signature: RSASHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), privateKey) ``` ### JWT Best Practices ``` DO: [x] Use asymmetric keys (RS256, ES256) -- not HS256 for multi-service [x] Set short expiry (15min) for access tokens [x] Include only necessary claims (keep token small) [x] Validate iss, aud, exp, nbf on every request [x] Use kid (Key ID) for key rotation [x] Store signing keys securely (KMS, Vault) [x] Implement token revocation via jti blacklist or short TTL DO NOT: [x] Store sensitive data in JWT payload (it is base64, not encrypted) [x] Use JWTs as session storage (no logout capability without blacklist) [x] Trust JWT without signature verification [x] Accept "alg": "none" (algorithm confusion attack) [x] Use long-lived access tokens (>1 hour) ``` ### Token Pair Strategy ``` ACCESS TOKEN: - Short-lived (15 minutes) - Sent with every API request (Authorization: Bearer <token>) - Contains identity and permissions - Stateless verification (no database lookup) REFRESH TOKEN: - Long-lived (7-30 days) - Stored securely (httpOnly cookie or secure storage) - Used ONLY to obtain new access tokens - Stored in database (allows revocation) - One-time use (rotate on each refresh) ``` ```ts // Token refresh flow async function refreshTokens(refreshToken: string): Promise<TokenPair> { // 1. Validate refresh token exists in database const storedToken = await db.refreshTokens.findUnique({ where: { token: hashToken(refreshToken) }, }); if (!storedToken || storedToken.revokedAt || storedToken.expiresAt < new Date()) { // Possible token theft -- revoke entire family if (storedToken?.familyId) { await db.refreshTokens.updateMany({ where: { familyId: storedToken.familyId }, data: { revokedAt: new Date() }, }); } throw new UnauthorizedException('Invalid refresh token'); } # ... (condensed) ... familyId: storedToken.familyId, expiresAt: addDays(new Date(), 30), }, }); return { accessToken, refreshToken: newRefreshToken }; } ``` ## OAuth 2.0 / OIDC Flows ### Flow Selection ``` FLOW USE CASE ------------------------------------------------------------- Authorization Code + PKCE Web apps, mobile apps, SPAs (RECOMMENDED) Client Credentials Machine-to-machine (no user) Device Code Smart TVs, CLI tools, IoT Implicit (DEPRECATED) Do not use -- use Auth Code + PKCE instead ROPC (DEPRECATED) Do not use -- legacy password grant ``` ### Authorization Code + PKCE Flow ``` PKCE (Proof Key for Code Exchange): Prevents authorization code interception attacks. Required for public clients (SPAs, mobile apps). Recommended for ALL clients. FLOW: 1. Client generates code_verifier (random string) and code_challenge (SHA256 hash of verifier) 2. Client redirects user to authorization server: GET /authorize? response_type=code& client_id=CLIENT_ID& redirect_uri=[reference URL] scope=openid profile email& state=random_state_value& code_challenge=BASE64URL(SHA256(code_verifier))& code_challenge_method=S256 # ... (condensed) ... { "access_token": "eyJ...", "refresh_token": "dGhpcyBpcyBh...", "id_token": "eyJ...", // OIDC "token_type": "Bearer", "expires_in": 900 } ``` ```ts // PKCE implementation import { randomBytes, createHash } from 'crypto'; function generatePKCE() { const verifier = randomBytes(32).toString('base64url'); const challenge = createHash('sha256').update(verifier).digest('base64url'); return { verifier, challenge }; } // Store verifier in session/cookie, send challenge to /authorize const { verifier, challenge } = generatePKCE(); session.codeVerifier = verifier; const authorizeUrl = new URL('[reference URL]'); authorizeUrl.searchParams.set('response_type', 'code'); authorizeUrl.searchParams.set('client_id', CLIENT_ID); authorizeUrl.searchParams.set('redirect_uri', REDIRECT_URI); authorizeUrl.searchParams.set('scope', 'openid profile email'); authorizeUrl.searchParams.set('state', generateState()); authorizeUrl.searchParams.set('code_challenge', challenge); authorizeUrl.searchParams.set('code_challenge_method', 'S256'); ``` ## Session Management ### Session Strategy Selection ``` JWT (Stateless): + No server-side storage + Scales horizontally without shared state + Fast verification (no DB lookup) - Cannot revoke individual tokens (without blacklist) - Token size grows with claims - Best for: APIs, microservices, short-lived operations Server Sessions (Stateful): + Immediate revocation (delete session) + Small cookie (just session ID) + Full control over session data - Requires server-side storage (Redis, DB) - Must handle session affinity or shared storage - Best for: Traditional web apps, apps needing instant logout HYBRID (Recommended for most apps): - Short-lived JWT access token (15min, stateless) - Server-side refresh token (30 days, in database) - Best of both worlds ``` ### Secure Cookie Configuration ```ts // Session cookie settings const sessionCookie = { name: '__session', httpOnly: true, // Not accessible via JavaScript secure: true, // HTTPS only sameSite: 'lax', // CSRF protection ('strict' for high-security) path: '/', domain: '.example.com', maxAge: 60 * 60 * 24 * 30, // 30 days }; // CSRF token cookie (readable by JavaScript for form submission) const csrfCookie = { name: '__csrf', httpOnly: false, // JavaScript needs to read this secure: true, sameSite: 'strict', path: '/', }; ``` ## RBAC (Role-Based Access Control) ```ts // Role and permission definitions const ROLES = { admin: { permissions: ['users:read', 'users:write', 'users:delete', 'orders:read', 'orders:write', 'settings:manage'], }, editor: { permissions: ['users:read', 'orders:read', 'orders:write', 'content:read', 'content:write'], }, viewer: { permissions: ['users:read', 'orders:read', 'content:read'], }, } as const; // Authorization middleware function requirePermission(...requiredPermissions: string[]) { return (req: Request, res: Response, next: NextFunction) => { # ... (condensed) ... next(); }; } // Usage app.delete('/api/users/:id', requirePermission('users:delete'), deleteUser); app.get('/api/orders', requirePermission('orders:read'), listOrders); ``` ## ABAC (Attribute-Based Access Control) ```ts // More flexible than RBAC -- uses attributes of user, resource, and context interface AccessPolicy { effect: 'allow' | 'deny'; conditions: PolicyCondition[]; } interface PolicyCondition { attribute: string; // user.role, resource.owner, context.time operator: 'eq' | 'in' | 'gt' | 'lt' | 'match'; value: any; } // Example policies const policies: AccessPolicy[] = [ { effect: 'allow', conditions: [ { attribute: 'user.role', operator: 'eq', value: 'admin' }, # ... (condensed) ... for (const policy of policies) { if (policy.conditions.every(c => matchCondition(c, user, resource, action))) { return policy.effect === 'allow'; } } return false; // Default deny } ``` ## MFA Implementation ```ts // TOTP (Time-based One-Time Password) setup import { authenticator } from 'otplib'; // Enrollment async function enrollMFA(userId: string): Promise<MFASetup> { const secret = authenticator.generateSecret(); // Store encrypted secret await db.users.update({ where: { id: userId }, data: { mfaSecret: encrypt(secret), mfaEnabled: false }, }); const otpauthUrl = authenticator.keyuri( user.email, 'MyApp', secret ); # ... (condensed) ... data: { mfaBackupCodes: user.mfaBackupCodes }, }); return generateTokenPair(user); } throw new UnauthorizedException('Invalid MFA token'); } ``` ## API Key Management ```ts // API key generation and storage async function createApiKey(userId: string, name: string): Promise<ApiKeyResponse> { const keyId = 'key_' + randomBytes(8).toString('hex'); const secret = randomBytes(32).toString('base64url'); const fullKey = `${keyId}.${secret}`; await db.apiKeys.create({ data: { id: keyId, hashedSecret: hashToken(secret), userId, name, permissions: ['read'], lastUsedAt: null, expiresAt: addDays(new Date(), 365), }, }); # ... (condensed) ... where: { id: keyId }, data: { lastUsedAt: new Date() }, }); req.user = { id: apiKey.userId, permissions: apiKey.permissions }; next(); } ``` ## SSO Integration ``` PROTOCOLS: SAML 2.0: Enterprise SSO (Okta, Azure AD, OneLogin) OIDC: Modern SSO (Google, Auth0, Keycloak) SAML FLOW: 1. User accesses Service Provider (SP) 2. SP redirects to Identity Provider (IdP) with SAML AuthnRequest 3. User authenticates at IdP 4. IdP sends SAML Response to SP's ACS endpoint 5. SP validates SAML assertion and creates session OIDC FLOW: Standard Authorization Code + PKCE flow IdP returns id_token with user identity claims ``` ## Security Hardening ``` PASSWORD STORAGE: - Use bcrypt (cost factor 12) or Argon2id - Never store plaintext or MD5/SHA hashes - bcrypt has built-in salt RATE LIMITING AUTH ENDPOINTS: - Login: 5 attempts per 15 minutes per IP/account - MFA: 5 attempts per 15 minutes - Password reset: 3 requests per hour per email - API key creation: 10 per hour BRUTE FORCE PROTECTION: - Progressive delays after failed attempts - Account lockout after N failures (with unlock flow) - CAPTCHA after 3 failed attempts TOKEN SECURITY: - Hash refresh tokens and API keys before storage - Use timing-safe comparison for token validation - Rotate signing keys periodically (with kid header) ``` ## Auth Architecture Checklist - [ ] Passwords hashed with bcrypt (cost 12+) or Argon2id - [ ] JWT access tokens short-lived (15 minutes) - [ ] Refresh tokens stored hashed in database, rotated on use - [ ] PKCE used for all OAuth flows (including confidential clients) - [ ] RBAC or ABAC implemented for authorization - [ ] MFA available with TOTP and backup codes - [ ] API keys hashed before storage, shown only once - [ ] Rate limiting on all auth endpoints - [ ] Secure cookie settings (httpOnly, secure, sameSite) - [ ] CSRF protection for cookie-based auth - [ ] Token revocation mechanism in place - [ ] Signing keys rotated with kid-based selection - [ ] Audit logging for auth events (login, logout, permission changes) - [ ] Account lockout after repeated failures ## When to Use **Use this skill when:** - Designing or implementing auth engineer solutions - Reviewing or improving existing auth engineer approaches - Making architectural or implementation decisions about auth engineer - Learning auth engineer patterns and best practices - Troubleshooting auth engineer-related issues