TOTP in Offline Mode

📴 Offline Considerations for TOTP – REL-ID SDK

🧭 What "Offline" Means

In REL-ID SDK, offline mode refers to scenarios where:

Server communication is not possible or deliberately restricted
Device must perform local authentication and OTP generation
Common in secure environments, travel, rural use cases, etc.

🔐 Offline TOTP Support

REL-ID SDK can generate TOTP without a server connection if the following conditions are met:

✅ Prerequisites

Requirement	Description
✅ Pre-authenticated session	User must have previously authenticated online
✅ Provisioned TOTP secret	Server must have issued TOTP seed/token during setup
✅ LDA configured (Fingerprint, Pattern)	Used for local identity verification before TOTP generation

🔁 Offline Behavior of onTOTPGenerated

Condition	Will `onTOTPGenerated` be triggered?
Device has LDA or cached password auth	✅ Yes
TOTP secret/token was provisioned earlier	✅ Yes
SDK policy allows offline OTP generation	✅ Yes
Device lacks LDA + password not cached	❌ No – SDK cannot generate OTP
Device TOTP setup was never completed online	❌ No – missing cryptographic seed

📋 TOTP Flow in Offline Mode

flowchart TD
    A[🌐 App Detects Offline Environment] --> A1[App calls fetchRegisteredTOTPUsers]
    A1 -->|User registered for TOTP| A2[App shows Generate TOTP option]
    A2 --> B[🧑 User Selects 'Generate TOTP']
    B --> C[🔍 SDK Checks for LDA or Cached Credentials]
    
    C -->|✅ LDA Available| D1[🔓 Perform Local Biometric/Pattern Auth]
    C -->|❌ LDA Not Available| D2[🔑 Fallback to Password Validation SDK triggers getTOTPPassword]
    D2 --> D3[App calls setTOTPPassword]
    D3 --> E[🧮 SDK Generate TOTP via Local Algorithm]
    D1 --> E
    E --> F[SDK emits onTOTPGenerated]
    F --> G[📲 App Displays TOTP and Expiry Timer]

    %% Success Callback Styling
    style C fill:#d4fdd4,stroke:#228b22,stroke-width:2px
    style F fill:#d4fdd4,stroke:#228b22,stroke-width:2px
    style onIDVAdditionalDocumentScan fill:#d4fdd4,stroke:#228b22,stroke-width:2px

    %% App-Initiated Call Styling
    style A1 fill:#ffe4b3,stroke:#ff8c00,stroke-width:2px
    style D3 fill:#ffe4b3,stroke:#ff8c00,stroke-width:2px

🟩 Green - Callbacks issued by REL-ID SDK
🟧 Orange - APIs invoked by the Client App

🔄 Comparison: Online vs Offline TOTP

Feature	Online TOTP	Offline TOTP
Server Required	✅ Yes	❌ No
LDA Required	Optional (based on policy)	✅ Yes (mandatory for local challenge)
Password Prompt	May be required	Only if LDA unavailable
Secret Provisioning	Live via server	Cached from earlier session
Verification Method	Server-side OTP match	Consuming app/server must validate

🧠 Developer Best Practices

✅ Prompt user to enable LDA during initial login.
✅ Use fetchRegisteredTOTPUsers() to check eligibility in advance.
✅ Cache fallback flags or TOTP readiness when connected.
❌ Do not attempt generateTOTP() offline unless prerequisites are met.
✅ Always show retry/fallback options when offline auth fails.

🔍 Notes for Developers

This flow is entirely local and does not require network connectivity.
Ensure biometric/pattern authentication is properly configured during activation.
Fallback to cached password depends on prior successful login and policy settings.
TOTP is time-based and will auto-expire as per the configured validity duration.

Updated 8 months ago