ContextQMD
Back to Router

Authentication

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

1.166.77.8 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

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

🛠️ DIY Authentication

Build your own authentication system using TanStack Start's server functions and session management:

  • Full Control: Complete customization over authentication flow
  • Server Functions: Secure authentication logic on the server
  • Session Management: Built-in session handling with HTTP-only cookies
  • 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

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

Resources

Implementation Guides:

Foundation Concepts:

Step-by-Step Tutorials: