Web Authentication

Web Authentication

Purpose

Plan how users prove identity and how the app carries that proof: the session/token model, where credentials live in the browser, how SSR and middleware see auth state, and the login/refresh/logout lifecycle. Enforcement is server-side, always.

When to Use

• When the app has any authenticated surface (customer app, dashboard).
• When reviewing or replacing an existing auth setup (existing-web-audit findings).
• Not for role/permission gating (web-authorization) or backend identity design.

Inputs

• Auth requirements: providers (email/password, OAuth/OIDC, SSO), MFA needs, session length.
• Backend boundary (web-api-integration) and framework foundation (SSR changes the options).
• Compliance/security constraints (../../security-review, ../../../system/SECURITY_RULES.md).

Discovery Questions

• Build on a managed provider (Auth0/Clerk/Supabase/NextAuth-style) or against an existing backend's auth — what does the evaluation say?
• Cookie sessions or bearer tokens? Same-origin or cross-origin API (cookie scope, CORS credentials)?
• Does SSR need the user (personalized server render), or is auth purely client-visible?
• Session lifetime, refresh policy, and "log out everywhere" requirements?

Responsibilities

• Credential input rules (email normalization, password policy, confirm match) come from ../../auth-form-validation — one schema, enforced on the server too.

• Decide the credential carrier: prefer httpOnly, Secure, SameSite cookies for browser apps; treat localStorage-held tokens as XSS-readable and justify any use.

• Plan CSRF protection whenever cookies authenticate state-changing requests (SameSite plus token where needed).

• Plan SSR/middleware auth on Next.js: reading the session in middleware/server components, redirect flow for protected pages, no auth-only content leaking into static output.

• Evaluate managed providers vs self-managed as a decision with trade-offs (cost, lock-in, MFA/SSO needs).

• Define the lifecycle: login, refresh (single-flight, rotation), logout (server-side invalidation, not just client state clearing), session expiry UX.

• Keep client auth state a reflection of the server's decision — a hint for UX, never the gate.

Required Workflow

1. Gather providers, session, and compliance requirements.
2. Choose carrier + CSRF strategy against the backend origin layout.
3. Plan SSR/middleware integration (Next.js) or SPA boot auth check (Vite).
4. Define login/refresh/logout flows and failure UX.
5. Record the plan for Gate 2; route enforcement review to ../../security-review.

Decision Rules

• Default to httpOnly cookie sessions for same-origin apps; bearer tokens make sense mainly when a separate API/multiple clients demand them — then plan storage and refresh explicitly.
• Any secret the browser JS can read is compromised under XSS — design as if XSS happens (../../security-review).
• Middleware/route protection is routing UX; every API/server action re-checks identity itself.
• Managed provider vs self-managed is a recorded evaluation, not a default either way.

Rules

• No credentials, tokens, or session secrets in logs, error reports, or public env vars.
• Logout invalidates server-side; a cleared client store alone is not logout.
• Auth pages and redirects must not create open-redirect vectors (validate return paths).

Anti-Patterns

• JWTs in localStorage by habit, with no XSS story.
• Client-side "isLoggedIn" checks guarding data the API serves unauthenticated.
• Refresh logic that fans out (one refresh per parallel 401).
• Rolling custom crypto/session formats instead of vetted mechanisms.

Validation Checklist

• Provider/model evaluated and chosen with trade-offs.
• Credential carrier + CSRF strategy defined for the actual origin layout.
• SSR/middleware (or SPA boot) auth flow planned.
• Login/refresh/logout lifecycle defined, server-side invalidation included.
• Client state confirmed as hint-only; server enforcement points listed.

Definition of Done

A recorded authentication plan — provider decision, credential carrier, CSRF posture, SSR integration, and full session lifecycle — where every enforcement point is server-side and the client only reflects it.

Related Skills

web-authorization, web-api-integration, web-routing, ../../security-review, ../../environment-audit, dashboard-permissions, nextjs-foundation.

Related Knowledge

../../../knowledge/ (identity model, compliance constraints).

Related References

../../../references/web/ (auth flow notes — when populated).

Context Loading Guidance

• Requires: auth requirements, backend/origin layout, framework foundation.
• Does not require: UI detail, unrelated feature skills.
• May load: web-authorization next; ../../security-review for the enforcement review.
• Stop when: the auth plan is recorded for approval.

Token Efficiency Guidance

Decide from the origin/requirements summary. Record the model as carrier + lifecycle + enforcement points; don't restate general auth theory.