| name | auth-setup |
| description | Setting up authentication with guards, sessions, registration, password reset, gates/policies, and vendor views in Rudder |
| license | MIT |
| appliesTo | ["@rudderjs/auth"] |
| trigger | configuring guards/providers in `config/auth.ts`, vendoring auth views, wiring `Gate`/`Policy`, or working with password reset / email verification |
| skip | a route handler that just reads `Auth.user()` — no setup needed |
| metadata | {"author":"rudderjs"} |
Auth Setup
When to use this skill
Load when you're configuring guards/providers, vendoring auth views, wiring Gate/Policy authorization, or working with password reset / email verification. For depth, open the rule file matching your task.
Quick Reference
| Task | Open |
|---|
Provider setup — install deps, config/auth.ts, register provider, make User authenticatable | rules/provider-setup.md |
Reading the current user — auth(), Auth facade, RequireAuth / RequireGuest middleware, login/logout endpoints | rules/guards-and-handlers.md |
Login / register UI — vendor:publish auth views, registerAuthRoutes, custom paths and view ids | rules/auth-views.md |
Authorization — Gate.define, model Policy classes, before callbacks | rules/gates-and-policies.md |
Email verification + password reset — MustVerifyEmail, verificationUrl, PasswordBroker | rules/email-and-password-reset.md |
Key concepts (load once)
- AuthManager — process-wide DI singleton that creates fresh
SessionGuard instances per call. Never cached — cached guards leak _user across requests.
auth() helper — Laravel-style accessor returning the request-scoped AuthManager via AsyncLocalStorage.Auth facade — Auth.user(), Auth.check(), etc. — static class that proxies to currentAuth().- Middleware groups —
AuthMiddleware auto-installs on the web group only. API routes are stateless by default; use RequireBearer() + scope(...) (passport) for token auth per-route.
SessionGuard.user() soft-fails — returns null (not throw) when there's no ALS context, matching Laravel's Auth::user() semantics.- Peer deps:
@rudderjs/session and @rudderjs/hash are required peers. HashProvider must boot before AuthProvider (defaultProviders() orders this automatically).
Examples
See playground/config/auth.ts, playground/app/Models/User.ts, playground/routes/web.ts, and playground/app/Views/Auth/.
