Initial commit
This commit is contained in:
Zhongwei Li
370
assets/auth-flow-diagram.md
Normal file
370
assets/auth-flow-diagram.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user