371 lines
24 KiB
Markdown
371 lines
24 KiB
Markdown
# 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.
|