Auth Implementation

Auth Implementation

Build authentication correctly the first time. Auth is the #1 place engineers introduce security holes — this skill gives language-agnostic patterns for sessions, tokens, OAuth, password hashing, and authorization. It builds what security-review later audits; align terminology with that skill.

When to use

• Implementing login, session management, token issuance, or password hashing
• Adding OAuth2/OIDC (social login, SSO) or service-to-service authentication
• Building RBAC/ABAC authorization checks (verify ownership, not just auth)
• Choosing session-vs-token strategy and refresh-token rotation for a new app

Not for: auditing existing auth for vulnerabilities (use security-review); designing the auth architecture at system level (use architecture); general implementation workflow (use implement — this skill supplies the auth-domain patterns, not the slice/TDD loop).

Steps

1. Choose session vs token

First-party web app with a server you control → server-side sessions (httpOnly cookie). API-first, microservices, or cross-domain → JWT (stateless). Hybrid (session cookie + access token for API calls) is common and fine. See the decision matrix in [references/token-patterns.md](references/token-patterns.md). Never store tokens in localStorage.

2. Hash passwords correctly

bcrypt (cost ≥ 12), argon2id (preferred for new systems), or scrypt. These algorithms generate and embed a per-password salt internally — do not roll your own salt. Verify with the library's constant-time compare (bcrypt.compare, not ===). Never MD5, SHA-1, or SHA-256 for passwords — they are too fast to resist brute force.

3. Session management (if session-based)

• Cookie flags: httpOnly (no JS access), secure (HTTPS only), sameSite=Lax (or Strict for same-site forms).
• Rotate the session ID on login and on any privilege change.
• Set absolute + idle timeout; extend idle on activity.
• Server-side invalidation on logout — delete the session record, do not just clear the cookie.

4. JWT (if token-based)

• Claims: sub (user id), exp (expiry), iat (issued), aud (audience), iss (issuer). Keep claims minimal — the token is visible to the holder.
• Access-token expiry ≤ 15 min. Never put secrets in a JWT payload — it is base64, not encrypted.
• Refresh tokens: long-lived, server-side state, rotated on every use. Reuse detection: if a refresh token is presented twice, invalidate the entire chain (both tokens are compromised). See [references/token-patterns.md](references/token-patterns.md).
• Revocation: maintain a denylist (jti) for logout-before-expiry and breach response. Stateless JWT cannot be revoked without server state — plan for this.

5. OAuth2 / OIDC flows

• SPAs and mobile: Authorization Code + PKCE. No client secret in the browser.
• Service-to-service: Client Credentials grant, with private_key_jwt or mTLS over shared secrets.
• Implicit flow is deprecated — do not use it. Token Exchange (RFC 8693) delegates access across services. See [references/oauth-flows.md](references/oauth-flows.md).
• Keep tokens server-side when possible; for SPAs, use a backend-for-frontend (BFF) so tokens stay off the client.

6. Authorization checks

Authentication ≠ authorization. "Who are you?" vs "are you allowed?". On every protected endpoint:

• Verify resource ownership: if (task.ownerId !== req.user.id) return 403 — not just if (!req.user) return 401.
• RBAC for role-gated actions (admin, editor); ABAC when ownership + role are insufficient (e.g., "edit reports in your department").
• Check at the data layer too — never assume the route guard covered it. IDOR (insecure direct object reference) is the #1 access-control bug.

7. CSRF and common pitfalls

• CSRF (cookie-based auth): send a per-session CSRF token in a header; validate on state-changing requests. sameSite reduces but does not eliminate CSRF. Token-based auth (Authorization header) is not CSRF-vulnerable by default.
• Timing attacks: use constant-time compare for tokens and secrets. === leaks length via response time.
• Refresh-token reuse: rotate + detect reuse (Step 4). No reuse detection = a stolen refresh token works forever.
• Token in URL: never — URLs land in logs, browser history, and Referer headers. Use headers or POST body.
• Rate-limit auth endpoints: login, register, password-reset (e.g., 10 / 15 min).
• Error messages: "invalid username or password" — do not reveal which field is wrong (user enumeration).

Verify

• [ ] Passwords hashed with bcrypt / argon2id / scrypt (never plaintext, MD5, or SHA)
• [ ] Tokens and sessions never stored in localStorage or client-accessible JS
• [ ] Session cookies carry httpOnly + secure + sameSite
• [ ] Access tokens short-lived (≤ 15 min); refresh tokens rotated with reuse detection
• [ ] Authorization (ownership or role) checked on every protected endpoint — not just authentication
• [ ] Auth endpoints rate-limited; error messages do not leak which field failed
• [ ] OAuth uses Authorization Code + PKCE (or Client Credentials for M2M), never Implicit
• [ ] No tokens in URL parameters or logs

References

• [${CLAUDEPLUGINROOT}/references/engineering-principles.md](${CLAUDEPLUGINROOT}/references/engineering-principles.md) — discipline every skill shares
• [references/token-patterns.md](references/token-patterns.md) — session-vs-token decision matrix, JWT structure, refresh-token rotation + reuse detection, revocation strategies
• [references/oauth-flows.md](references/oauth-flows.md) — Authorization Code + PKCE, Client Credentials, Implicit deprecation, Token Exchange (RFC 8693)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: int2t05
• Source: int2t05/engineering-skills
• License: MIT

Install and usage instructions live in the source repository linked above.