Authentication Flow Diagrams

Visual representation of authentication flows for each mode.

Password-Only Authentication

sequenceDiagram
    participant User
    participant Browser
    participant IDS as Identity Server
    participant DB as Database

    User->>Browser: Enter email + password
    Browser->>IDS: POST /interaction/:uid/login
    IDS->>DB: Validate credentials
    DB-->>IDS: User validated
    IDS->>DB: Check team access
    DB-->>IDS: Access granted
    IDS-->>Browser: Redirect to callback
    Browser-->>User: Logged in

OTP-Only Authentication (Passwordless)

sequenceDiagram
    participant User
    participant Browser
    participant IDS as Identity Server
    participant OTP as OTP Service
    participant DB as Database

    User->>Browser: Enter email/mobile
    Browser->>IDS: POST /interaction/:uid/login
    IDS->>DB: Find user
    DB-->>IDS: User found
    IDS->>OTP: Generate OTP
    OTP->>OTP: Store hashed OTP
    OTP-->>User: Send OTP (email/SMS)
    IDS-->>Browser: Render OTP form
    
    User->>Browser: Enter OTP
    Browser->>IDS: POST /interaction/:uid/otp
    IDS->>OTP: Verify OTP
    OTP->>DB: Check OTP validity
    DB-->>OTP: OTP valid
    OTP-->>IDS: Verified
    IDS->>DB: Check team access
    DB-->>IDS: Access granted
    IDS-->>Browser: Redirect to callback
    Browser-->>User: Logged in

Two-Factor Authentication (2FA)

sequenceDiagram
    participant User
    participant Browser
    participant IDS as Identity Server
    participant OTP as OTP Service
    participant DB as Database
    participant Session

    Note over User,DB: Step 1: Password Verification
    User->>Browser: Enter email + password
    Browser->>IDS: POST /interaction/:uid/login
    IDS->>DB: Validate password
    DB-->>IDS: Password valid
    IDS->>OTP: Generate OTP
    OTP->>OTP: Store hashed OTP
    OTP-->>User: Send OTP (email/SMS)
    IDS->>Session: Store pendingUserId
    IDS-->>Browser: Render OTP form (Step 2)
    
    Note over User,DB: Step 2: OTP Verification
    User->>Browser: Enter OTP
    Browser->>IDS: POST /interaction/:uid/otp
    IDS->>Session: Get pendingUserId
    Session-->>IDS: User ID
    IDS->>OTP: Verify OTP
    OTP->>DB: Check OTP validity
    DB-->>OTP: OTP valid
    OTP-->>IDS: Verified
    IDS->>Session: Clear pendingUserId
    IDS->>DB: Check team access
    DB-->>IDS: Access granted
    IDS-->>Browser: Redirect to callback
    Browser-->>User: Logged in

Flexible Authentication

Option A: User Chooses Password

sequenceDiagram
    participant User
    participant Browser
    participant IDS as Identity Server
    participant DB as Database

    User->>Browser: Enter email + password
    Browser->>IDS: POST /interaction/:uid/login
    Note over IDS: Password provided → validate
    IDS->>DB: Validate credentials
    DB-->>IDS: User validated
    IDS->>DB: Check team access
    DB-->>IDS: Access granted
    IDS-->>Browser: Redirect to callback
    Browser-->>User: Logged in

Option B: User Chooses OTP

sequenceDiagram
    participant User
    participant Browser
    participant IDS as Identity Server
    participant OTP as OTP Service
    participant DB as Database

    User->>Browser: Enter email (no password)
    Browser->>IDS: POST /interaction/:uid/login
    Note over IDS: No password → trigger OTP
    IDS->>DB: Find user
    DB-->>IDS: User found
    IDS->>OTP: Generate OTP
    OTP->>OTP: Store hashed OTP
    OTP-->>User: Send OTP (email/SMS)
    IDS-->>Browser: Render OTP form
    
    User->>Browser: Enter OTP
    Browser->>IDS: POST /interaction/:uid/otp
    IDS->>OTP: Verify OTP
    OTP->>DB: Check OTP validity
    DB-->>OTP: OTP valid
    OTP-->>IDS: Verified
    IDS->>DB: Check team access
    DB-->>IDS: Access granted
    IDS-->>Browser: Redirect to callback
    Browser-->>User: Logged in

Mobile Number Login Flow

sequenceDiagram
    participant User
    participant Browser
    participant IDS as Identity Server
    participant DB as Database

    User->>Browser: Enter mobile number (+1234567890)
    Browser->>IDS: POST /interaction/:uid/login
    Note over IDS: enable_mobile_login = true
    IDS->>DB: Find user by mobile OR email
    DB-->>IDS: User found
    Note over IDS: Continue with configured auth_mode
    IDS-->>Browser: Password/OTP flow

Configuration Decision Tree

graph TD
    A[Choose Authentication Mode] --> B{Security Requirements?}
    B -->|Low| C[Password Only]
    B -->|Medium| D{User Preference?}
    B -->|High| E[2FA]
    B -->|Very High| E
    
    D -->|Important| F[Flexible]
    D -->|Not Important| G{Passwordless?}
    
    G -->|Yes| H[OTP Only]
    G -->|No| C
    
    C --> I[Configure Client]
    H --> I
    E --> I
    F --> I
    
    I --> J{Mobile Login?}
    J -->|Yes| K[Enable mobile_login]
    J -->|No| L[Email only]
    
    K --> M{OTP Delivery?}
    L --> M
    
    M --> N[Email/SMS/Both]
    N --> O[Save Configuration]
    
    style E fill:#ff9999
    style H fill:#99ff99
    style F fill:#9999ff
    style C fill:#99ccff

Authentication Mode Comparison

graph LR
    subgraph "Password Only"
        P1[Email/Mobile] --> P2[Password]
        P2 --> P3[Login]
    end
    
    subgraph "OTP Only"
        O1[Email/Mobile] --> O2[Send OTP]
        O2 --> O3[Enter OTP]
        O3 --> O4[Login]
    end
    
    subgraph "2FA"
        T1[Email/Mobile] --> T2[Password]
        T2 --> T3[Send OTP]
        T3 --> T4[Enter OTP]
        T4 --> T5[Login]
    end
    
    subgraph "Flexible"
        F1[Email/Mobile] --> F2{Password?}
        F2 -->|Yes| F3[Login]
        F2 -->|No| F4[Send OTP]
        F4 --> F5[Enter OTP]
        F5 --> F6[Login]
    end

Security Levels

graph TD
    A[Authentication Modes] --> B[Password Only]
    A --> C[OTP Only]
    A --> D[Flexible]
    A --> E[2FA]
    
    B --> B1["⭐⭐⭐ Medium Security"]
    C --> C1["⭐⭐⭐⭐ High Security"]
    D --> D1["⭐⭐⭐⭐ High Security"]
    E --> E1["⭐⭐⭐⭐⭐ Very High Security"]
    
    B1 --> B2[Single Factor]
    C1 --> C2[Time-Limited Codes]
    D1 --> D2[User Choice]
    E1 --> E2[Multi-Factor]
    
    style E1 fill:#90EE90
    style C1 fill:#87CEEB
    style D1 fill:#DDA0DD
    style B1 fill:#FFB6C1

OTP Lifecycle

stateDiagram-v2
    [*] --> Generated: User requests OTP
    Generated --> Sent: Deliver via email/SMS
    Sent --> Pending: Awaiting verification
    Pending --> Verified: User enters correct OTP
    Pending --> Expired: 5 minutes elapsed
    Pending --> Invalid: Wrong OTP entered
    Verified --> [*]: Login successful
    Expired --> [*]: Request new OTP
    Invalid --> Pending: Retry (rate limited)

Session State (2FA)

stateDiagram-v2
    [*] --> PasswordStep: User enters password
    PasswordStep --> PasswordValidated: Password correct
    PasswordValidated --> OTPGenerated: Generate & send OTP
    OTPGenerated --> SessionStored: Store pendingUserId
    SessionStored --> OTPStep: Show OTP form
    OTPStep --> OTPVerified: OTP correct
    OTPVerified --> SessionCleared: Clear pendingUserId
    SessionCleared --> [*]: Login complete
    
    PasswordStep --> [*]: Password incorrect
    OTPStep --> [*]: OTP incorrect/expired

Legend

• IDS: Identity Server
• OTP: One-Time Password Service
• DB: Database
• Session: Session Store

Notes

1. All OTP codes expire after 5 minutes
2. OTPs are stored hashed in the database
3. Session state is used for 2FA to link password and OTP steps
4. Team access is checked before final login
5. Mobile login works with all authentication modes