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

Server Function Guards

• Server-side validation before executing sensitive operations
• Works alongside route-level protection
• Essential for API security regardless of client-side protection

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#

• WorkOS
• Clerk

🛠️ 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 with getRequestHeader
• 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:

• Clerk Integration
• WorkOS Integration

DIY Implementations:

• Basic Auth with Prisma
• Supabase Auth

Client-Side Examples:

• Basic Authentication
• Firebase Auth

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

Security Considerations#

• Use HTTPS in production
• Use HTTP-only cookies when possible
• Validate all inputs on the server
• Keep secrets in server-only functions
• Implement rate limiting for auth endpoints
• Use CSRF protection for form submissions

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:

• Execution Model
• Server Functions

Step-by-Step Tutorials:

• Router How-to Guides