9.2 KiB
| id | title |
|---|---|
| authentication-overview | Authentication |
Authentication vs Authorization
- Authentication: Who is this user? (Login/logout, identity verification)
- Authorization: What can this user do? (Permissions, roles, access control)
Architecture Overview
Full-Stack Authentication Model
Server-Side (Secure)
- Session storage and validation
- User credential verification
- Database operations
- Token generation/verification
- Protected API endpoints
Client-Side (Public)
- Authentication state management
- Route protection logic
- Login/logout user interface
- Redirect handling
Isomorphic (Both)
- Route loaders checking auth state
- Shared validation logic
- User profile data access
Session Management Patterns
HTTP-Only Cookies (Recommended)
- Most secure approach - not accessible via JavaScript
- Automatic browser handling
- Built-in CSRF protection with
sameSite - Best for traditional web applications
JWT Tokens
- Stateless authentication
- Good for API-first applications
- Requires careful handling to avoid XSS vulnerabilities
- Consider refresh token rotation
Server-Side Sessions
- Centralized session control
- Easy to revoke sessions
- Requires session storage (database, Redis)
- Good for applications requiring immediate session control
Route Protection Architecture
Layout Route Pattern (Recommended)
- Protect entire route subtrees with parent layout routes
- Centralized authentication logic
- Automatic protection for all child routes
- Clean separation of authenticated vs public routes
Component-Level Protection
- Conditional rendering within components
- More granular control over UI states
- Good for mixed public/private content on same route
- Requires careful handling to prevent layout shifts
Data/API Protection (Security Boundary)
- Authorize every server function, server route, or API endpoint that reads or writes private data
- Reject unauthorized requests even if no protected route was loaded first
- Treat route guards as UX and navigation control, not as the data boundary
State Management Patterns
Server-Driven State (Recommended)
- Authentication state sourced from server on each request
- Always up-to-date with server state
- Works seamlessly with SSR
- Best security - server is source of truth
Context-Based State
- Client-side authentication state management
- Good for third-party auth providers (Auth0, Firebase)
- Requires careful synchronization with server state
- Consider for highly interactive client-first applications
Hybrid Approach
- Initial state from server, client-side updates
- Balance between security and UX
- Periodic server-side validation
Authentication Options
🏢 Partner Solutions
🛠️ DIY Authentication
Build your own authentication system using TanStack Start's server functions and session management. Start with the Authentication Server Primitives guide — it covers session cookies (HttpOnly/Secure/SameSite/__Host-), session lookup as middleware, OAuth state + PKCE, password-reset enumeration defense, CSRF, rate limiting, and session rotation, with the WRONG/CORRECT patterns that catch the common mistakes.
- Full Control: Complete customization over authentication flow
- Server Primitives: Sessions, OAuth, CSRF, rate limiting — see Authentication Server Primitives
- Session Management: HTTP-only cookies via
setResponseHeader, read withgetRequestHeader - Type Safety: End-to-end type safety for authentication state
🌐 Other Excellent Options
Open Source & Community Solutions:
- Better Auth - Modern, TypeScript-first authentication library
- Auth.js (formerly NextAuth.js) - Popular authentication library for React
Hosted Services:
- Supabase Auth - Open source Firebase alternative with built-in auth
- Auth0 - Established authentication platform with extensive features
- Firebase Auth - Google's authentication service
Partner Solutions
WorkOS - Enterprise Authentication
- Single Sign-On (SSO) - SAML, OIDC, and OAuth integrations
- Directory Sync - SCIM provisioning with Active Directory and Google Workspace
- Multi-factor Authentication - Enterprise-grade security options
- Compliance Ready - SOC 2, GDPR, and CCPA compliant
Visit WorkOS → | View example →
Clerk - Complete Authentication Platform
- Ready-to-use UI Components - Sign-in, sign-up, user profile, and organization management
- Social Logins - Google, GitHub, Discord, and 20+ providers
- Multi-factor Authentication - SMS, TOTP, and backup codes
- Organizations & Teams - Built-in support for team-based applications
Visit Clerk → | Sign up free → | View example →
Examples
Partner Solutions:
DIY Implementations:
Client-Side Examples:
Architecture Decision Guide
Choosing an Authentication Approach
Partner Solutions:
- Focus on your core business logic
- Enterprise features (SSO, compliance)
- Managed security and updates
- Pre-built UI components
OSS Solutions:
- Community-driven development
- Specific customizations
- Self-hosted solutions
- Avoid vendor lock-in
DIY Implementation:
- Complete control over the auth flow
- Custom security requirements
- Specific business logic needs
- Full ownership of authentication data
Production Auth Checklist
- Use HTTPS in production and set a strong session secret.
- Store sessions in
HttpOnly,Secure,SameSitecookies. Do not store session tokens inlocalStorageorsessionStorage. - Enforce auth in every server function, server route, or API endpoint that reads or writes private user, tenant, or account data. Use
beforeLoadfor page UX, not as the data boundary. - Use
.validator()on every server function that accepts input. - Hash passwords with bcrypt, scrypt, or Argon2. For missing users, verify against a dummy hash and return the same login/reset message.
- Rate limit login, registration, and password-reset endpoints.
- Use CSRF or same-origin protections for non-GET server functions and server routes.
- Log authentication events and monitor failures.
- Test direct unauthenticated calls to protected server functions; they should reject before returning data.
Next Steps
- Partner solutions → Clerk or WorkOS
- DIY implementation → Authentication Guide
- Examples → Working implementations
Resources
Implementation Guides:
- Authentication Server Primitives — sessions, cookies, OAuth, CSRF, rate limiting (the server half)
- Authentication Patterns
- Router Authentication Guide
Foundation Concepts:
Step-by-Step Tutorials: