24 KiB
24 KiB
better-auth Authentication Flow Diagrams
Visual representations of common authentication flows using better-auth.
1. Email/Password Sign-Up Flow
┌─────────┐ ┌─────────┐ ┌──────────┐
│ Client │ │ Worker │ │ D1 │
└────┬────┘ └────┬────┘ └────┬─────┘
│ │ │
│ POST /api/auth/signup │ │
│ { email, password } │ │
├──────────────────────────>│ │
│ │ Hash password (bcrypt) │
│ │ │
│ │ INSERT INTO users │
│ ├──────────────────────────>│
│ │ │
│ │ Generate verification │
│ │ token │
│ │ │
│ │ INSERT INTO │
│ │ verification_tokens │
│ ├──────────────────────────>│
│ │ │
│ │ Send verification email │
│ │ (via email service) │
│ │ │
│ { success: true } │ │
│<──────────────────────────┤ │
│ │ │
│ │ │
│ User clicks email link │ │
│ │ │
│ GET /api/auth/verify? │ │
│ token=xyz │ │
├──────────────────────────>│ │
│ │ Verify token │
│ ├──────────────────────────>│
│ │ │
│ │ UPDATE users SET │
│ │ email_verified = true │
│ ├──────────────────────────>│
│ │ │
│ Redirect to dashboard │ │
│<──────────────────────────┤ │
│ │ │
2. Social Sign-In Flow (Google OAuth)
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐
│ Client │ │ Worker │ │ D1 │ │ Google │
└────┬────┘ └────┬────┘ └────┬─────┘ └────┬────┘
│ │ │ │
│ Click "Sign │ │ │
│ in with │ │ │
│ Google" │ │ │
│ │ │ │
│ POST /api/ │ │ │
│ auth/signin/ │ │ │
│ google │ │ │
├────────────────>│ │ │
│ │ Generate OAuth │ │
│ │ state + PKCE │ │
│ │ │ │
│ Redirect to │ │ │
│ Google OAuth │ │ │
│<────────────────┤ │ │
│ │ │ │
│ │ │ │
│ User authorizes on Google │ │
├───────────────────────────────────────────────────────>│
│ │ │ │
│ │ │ User approves │
│<───────────────────────────────────────────────────────┤
│ │ │ │
│ Redirect to │ │ │
│ callback with │ │ │
│ code │ │ │
│ │ │ │
│ GET /api/auth/ │ │ │
│ callback/ │ │ │
│ google?code= │ │ │
├────────────────>│ │ │
│ │ Exchange code │ │
│ │ for tokens │ │
│ ├─────────────────────────────────────>│
│ │ │ │
│ │ { access_token, │ │
│ │ id_token } │ │
│ │<─────────────────────────────────────┤
│ │ │ │
│ │ Fetch user info │ │
│ ├─────────────────────────────────────>│
│ │ │ │
│ │ { email, name, │ │
│ │ picture } │ │
│ │<─────────────────────────────────────┤
│ │ │ │
│ │ Find or create │ │
│ │ user │ │
│ ├─────────────────>│ │
│ │ │ │
│ │ Store account │ │
│ │ (provider data) │ │
│ ├─────────────────>│ │
│ │ │ │
│ │ Create session │ │
│ ├─────────────────>│ │
│ │ │ │
│ Set session │ │ │
│ cookie + │ │ │
│ redirect │ │ │
│<────────────────┤ │ │
│ │ │ │
3. Session Verification Flow
┌─────────┐ ┌─────────┐ ┌──────────┐
│ Client │ │ Worker │ │ KV │
└────┬────┘ └────┬────┘ └────┬─────┘
│ │ │
│ GET /api/protected │ │
│ Cookie: session=xyz │ │
├───────────────────────>│ │
│ │ Extract session ID │
│ │ from cookie │
│ │ │
│ │ GET session from KV │
│ ├───────────────────────>│
│ │ │
│ │ { userId, expiresAt } │
│ │<───────────────────────┤
│ │ │
│ │ Check expiration │
│ │ │
│ If valid: │ │
│ { data: ... } │ │
│<───────────────────────┤ │
│ │ │
│ If invalid: │ │
│ 401 Unauthorized │ │
│<───────────────────────┤ │
│ │ │
4. Password Reset Flow
┌─────────┐ ┌─────────┐ ┌──────────┐
│ Client │ │ Worker │ │ D1 │
└────┬────┘ └────┬────┘ └────┬─────┘
│ │ │
│ POST /api/auth/ │ │
│ forgot-password │ │
│ { email } │ │
├───────────────────────>│ │
│ │ Find user by email │
│ ├───────────────────────>│
│ │ │
│ │ Generate reset token │
│ │ │
│ │ INSERT INTO │
│ │ verification_tokens │
│ ├───────────────────────>│
│ │ │
│ │ Send reset email │
│ │ │
│ { success: true } │ │
│<───────────────────────┤ │
│ │ │
│ │ │
│ User clicks email │ │
│ link │ │
│ │ │
│ GET /reset-password? │ │
│ token=xyz │ │
├───────────────────────>│ │
│ │ Verify token │
│ ├───────────────────────>│
│ │ │
│ Show reset form │ │
│<───────────────────────┤ │
│ │ │
│ POST /api/auth/ │ │
│ reset-password │ │
│ { token, password } │ │
├───────────────────────>│ │
│ │ Hash new password │
│ │ │
│ │ UPDATE users │
│ ├───────────────────────>│
│ │ │
│ │ DELETE token │
│ ├───────────────────────>│
│ │ │
│ Redirect to login │ │
│<───────────────────────┤ │
│ │ │
5. Two-Factor Authentication (2FA) Flow
┌─────────┐ ┌─────────┐ ┌──────────┐
│ Client │ │ Worker │ │ D1 │
└────┬────┘ └────┬────┘ └────┬─────┘
│ │ │
│ POST /api/auth/ │ │
│ signin │ │
│ { email, password } │ │
├───────────────────────>│ │
│ │ Verify credentials │
│ ├───────────────────────>│
│ │ │
│ │ Check if 2FA enabled │
│ ├───────────────────────>│
│ │ │
│ { requires2FA: true } │ │
│<───────────────────────┤ │
│ │ │
│ Show 2FA input │ │
│ │ │
│ POST /api/auth/ │ │
│ verify-2fa │ │
│ { code: "123456" } │ │
├───────────────────────>│ │
│ │ Get 2FA secret │
│ ├───────────────────────>│
│ │ │
│ │ Verify TOTP code │
│ │ │
│ If valid: │ │
│ Create session │ │
│ + redirect │ │
│<───────────────────────┤ │
│ │ │
6. Organization/Team Flow
┌─────────┐ ┌─────────┐ ┌──────────┐
│ Client │ │ Worker │ │ D1 │
└────┬────┘ └────┬────┘ └────┬─────┘
│ │ │
│ POST /api/org/create │ │
│ { name, slug } │ │
├───────────────────────>│ │
│ │ Verify session │
│ │ │
│ │ INSERT INTO orgs │
│ ├───────────────────────>│
│ │ │
│ │ INSERT INTO │
│ │ org_members │
│ │ (user as owner) │
│ ├───────────────────────>│
│ │ │
│ { org: { ... } } │ │
│<───────────────────────┤ │
│ │ │
│ │ │
│ POST /api/org/invite │ │
│ { orgId, email, │ │
│ role } │ │
├───────────────────────>│ │
│ │ Check permissions │
│ ├───────────────────────>│
│ │ │
│ │ Generate invite token │
│ │ │
│ │ INSERT INTO │
│ │ org_invitations │
│ ├───────────────────────>│
│ │ │
│ │ Send invite email │
│ │ │
│ { success: true } │ │
│<───────────────────────┤ │
│ │ │
Database Schema Overview
┌──────────────────────┐
│ users │
├──────────────────────┤
│ id (PK) │
│ email (UNIQUE) │
│ email_verified │
│ name │
│ image │
│ role │
│ created_at │
│ updated_at │
└──────────┬───────────┘
│
│ 1:N
│
┌──────────┴───────────┐ ┌──────────────────────┐
│ sessions │ │ accounts │
├──────────────────────┤ ├──────────────────────┤
│ id (PK) │ │ id (PK) │
│ user_id (FK) │◄───────┤ user_id (FK) │
│ expires_at │ │ provider │
│ ip_address │ │ provider_account_id │
│ user_agent │ │ access_token │
│ created_at │ │ refresh_token │
└──────────────────────┘ │ expires_at │
│ created_at │
└──────────────────────┘
┌──────────────────────┐
│ verification_tokens │
├──────────────────────┤
│ identifier │
│ token │
│ expires │
│ created_at │
└──────────────────────┘
┌──────────────────────┐ ┌──────────────────────┐
│ organizations │ │ organization_members │
├──────────────────────┤ ├──────────────────────┤
│ id (PK) │ │ id (PK) │
│ name │ │ organization_id (FK) │◄──┐
│ slug (UNIQUE) │◄───────┤ user_id (FK) │ │
│ logo │ │ role │ │
│ created_at │ │ created_at │ │
│ updated_at │ └──────────────────────┘ │
└──────────────────────┘ │
│
┌──────────────────────┐ │
│organization_invites │ │
├──────────────────────┤ │
│ id (PK) │ │
│ organization_id (FK) │────────────────────────────────────┘
│ email │
│ role │
│ invited_by (FK) │
│ token │
│ expires_at │
│ created_at │
└──────────────────────┘
These diagrams illustrate the complete authentication flows supported by better-auth. Use them as reference when implementing auth in your application.