ContextQMD
Back to Router

Authentication

docs/start/framework/react/guide/authentication-overview.md

1.166.79.2 KB
Original Source

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 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

<a href="https://workos.com/" alt="WorkOS Logo"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/workos-white.svg" width="280"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/workos-black.svg" width="280"> </picture> </a>
  • 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

<a href="https://go.clerk.com/wOwHtuJ" alt="Clerk Logo"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/clerk-logo-dark.svg" width="280"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tanstack/tanstack.com/main/src/images/clerk-logo-light.svg" width="280"> </picture> </a>
  • 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, SameSite cookies. Do not store session tokens in localStorage or sessionStorage.
  • Enforce auth in every server function, server route, or API endpoint that reads or writes private user, tenant, or account data. Use beforeLoad for 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

Resources

Implementation Guides:

Foundation Concepts:

Step-by-Step Tutorials: