Authentication Flows

AuthSec supports multiple authentication methods to meet diverse security requirements. This guide helps you choose the right authentication flow for your use case.

Authentication Methods Overview

Method	Use Case	Security Level	Complexity
Basic Login	Standard web/mobile apps	Medium	Low
MFA (WebAuthn)	High-security applications	High	Medium
MFA (TOTP)	Two-factor authentication	High	Low
MFA (SMS)	Consumer applications	Medium	Low
OIDC/Social Login	Quick onboarding, social apps	Medium	Medium
SAML SSO	Enterprise applications	High	High
Device Authorization	TV, IoT, limited input devices	Medium	Medium
CIBA	Banking, high-value transactions	Very High	High
Voice Biometrics	Call centers, voice apps	High	High

Basic Authentication Flow

Standard username/password authentication with JWT tokens.

Flow Diagram

sequenceDiagram
    participant User
    participant App
    participant UserFlow as User Flow API
    participant AuthMgr as Auth Manager
    
    User->>App: Enter credentials
    App->>UserFlow: POST /auth/login
    UserFlow->>UserFlow: Validate credentials
    UserFlow->>AuthMgr: Request JWT
    AuthMgr->>UserFlow: JWT token
    UserFlow->>App: access_token
    App->>User: Login successful
    
    Note over App,UserFlow: Subsequent requests
    App->>UserFlow: API request + Bearer token
    UserFlow->>AuthMgr: Validate token
    AuthMgr->>UserFlow: Token valid
    UserFlow->>App: Response

When to Use

• ✅ Standard web and mobile applications
• ✅ Internal tools and dashboards
• ✅ Development and testing

Endpoints

• Admin login: POST /uflow/admin/auth/login
• End user login: POST /uflow/auth/login

Documentation: User Management - Authentication

---

Multi-Factor Authentication (MFA)

WebAuthn (Biometric/Hardware Keys)

Passwordless or second-factor authentication using biometrics or hardware security keys.

sequenceDiagram
    participant User
    participant App
    participant UserFlow
    participant WebAuthn as WebAuthn Service
    participant AuthMgr as Auth Manager
    
    User->>App: Initiate login
    App->>UserFlow: POST /auth/login
    UserFlow->>WebAuthn: Request MFA challenge
    WebAuthn->>App: Challenge data
    App->>User: Prompt for biometric/key
    User->>App: Provide biometric/key
    App->>WebAuthn: POST /finishAuthentication
    WebAuthn->>WebAuthn: Verify credential
    WebAuthn->>AuthMgr: Request token
    AuthMgr->>App: access_token

When to Use:

• ✅ High-security applications (finance, healthcare)
• ✅ Passwordless authentication
• ✅ Compliance requirements (PCI-DSS, SOC 2)

Documentation: WebAuthn MFA

TOTP (Time-Based One-Time Password)

Authenticator app-based second factor (Google Authenticator, Authy, etc.)

sequenceDiagram
    participant User
    participant App
    participant UserFlow
    participant WebAuthn as WebAuthn Service
    
    Note over User,WebAuthn: Setup Phase
    App->>WebAuthn: POST /totp/begin Setup
    WebAuthn->>App: QR code + secret
    App->>User: Display QR code
    User->>User: Scan with authenticator app
    User->>App: Enter verification code
    App->>WebAuthn: POST /totp/confirmSetup
    WebAuthn->>App: Setup confirmed
    
    Note over User,WebAuthn: Login Phase
    App->>UserFlow: POST /auth/login
    UserFlow->>App: Require TOTP
    User->>App: Enter TOTP code
    App->>WebAuthn: POST /totp/verify
    WebAuthn->>App: Verified, return token

When to Use:

• ✅ Two-factor authentication for most apps
• ✅ Wide device compatibility needed
• ✅ No SMS costs desired

Documentation: TOTP MFA

SMS Verification

SMS-based one-time codes for second factor.

When to Use:

• ✅ Consumer applications
• ✅ Users without smartphones/authenticator apps
• ⚠️ Not recommended for high-security use cases

Documentation: SMS MFA

---

Federated Authentication

OIDC / Social Login

Allow users to authenticate with existing accounts (Google, Facebook, etc.)

sequenceDiagram
    participant User
    participant App
    participant UserFlow
    participant Provider as Identity Provider<br/>(Google, etc.)
    participant AuthMgr as Auth Manager
    
    User->>App: Click "Login with Google"
    App->>Provider: Redirect to provider
    User->>Provider: Authorize application
    Provider->>App: Authorization code
    App->>UserFlow: POST /oidc/callback<br/>with auth code
    UserFlow->>Provider: Exchange code for token
    Provider->>UserFlow: User profile + token
    UserFlow->>UserFlow: Create/link account
    UserFlow->>AuthMgr: Request JWT
    AuthMgr->>App: access_token

When to Use:

• ✅ Reduce friction in user onboarding
• ✅ Consumer applications
• ✅ Social platforms and community apps

Supported Providers:

• Google
• Microsoft
• Facebook
• GitHub
• Custom OIDC providers

Documentation: OIDC & Social Login

SAML SSO

Enterprise single sign-on for corporate identity providers.

sequenceDiagram
    participant User
    participant App as Service Provider<br/>(Your App)
    participant IdP as Identity Provider<br/>(Okta, Azure AD)
    participant UserFlow
    
    User->>App: Access protected resource
    App->>IdP: Redirect with SAML request
    User->>IdP: Authenticate
    IdP->>App: SAML assertion
    App->>UserFlow: Validate assertion
    UserFlow->>App: access_token
    App->>User: Grant access

When to Use:

• ✅ Enterprise B2B applications
• ✅ Corporate SSO requirements
• ✅ Integration with Okta, Azure AD, OneLogin

Documentation: SAML SSO

---

Specialized Flows

Device Authorization (OAuth 2.0 Device Flow)

For devices with limited input capabilities (smart TVs, IoT devices).

sequenceDiagram
    participant Device as Smart TV
    participant User
    participant Browser
    participant UserFlow
    participant AuthMgr as Auth Manager
    
    Device->>UserFlow: POST /device/authorize
    UserFlow->>Device: user_code + verification_uri
    Device->>User: Display: "Visit example.com/activate<br/>Enter code: ABCD-1234"
    User->>Browser: Navigate to verification_uri
    Browser->>UserFlow: Enter user_code
    User->>Browser: Approve device
    UserFlow->>AuthMgr: Issue token for device
    Device->>UserFlow: Poll for token
    UserFlow->>Device: access_token

When to Use:

• ✅ Smart TVs and streaming devices
• ✅ IoT devices without keyboards
• ✅ Gaming consoles

Documentation: Device Authorization

CIBA (Client Initiated Backchannel Authentication)

Decoupled authentication where authorization happens on a different device.

sequenceDiagram
    participant App as Application
    participant UserFlow
    participant User as User's Phone
    participant AuthMgr as Auth Manager
    
    App->>UserFlow: POST /ciba/initiate<br/>{user_identifier}
    UserFlow->>User: Push notification
    UserFlow->>App: auth_req_id
    App->>UserFlow: Poll for result
    User->>User: Review request
    User->>UserFlow: Approve/Deny
    UserFlow->>AuthMgr: Issue token (if approved)
    UserFlow->>App: access_token

When to Use:

• ✅ Banking and financial applications
• ✅ High-value transactions
• ✅ Strong authentication requirements

Documentation: CIBA

Voice Biometrics

Authenticate users by their voice patterns.

When to Use:

• ✅ Call center authentication
• ✅ Voice-activated applications
• ✅ Hands-free authentication

Documentation: Voice Authentication

---

Choosing the Right Flow

Decision Tree

graph TD
    Start[Choose Authentication Method] --> DeviceType{Device Type?}
    
    DeviceType -->|Web/Mobile| Security{Security Requirements?}
    DeviceType -->|TV/IoT| Device[Device Authorization]
    
    Security -->|Basic| Basic[Basic Login]
    Security -->|Enhanced| MFA{MFA Method?}
    Security -->|Maximum| CIBA[CIBA]
    
    MFA -->|Passwordless| WebAuthn[WebAuthn]
    MFA -->|2FA| Choice{User Preference?}
    
    Choice -->|Authenticator App| TOTP[TOTP]
    Choice -->|SMS| SMS[SMS Codes]
    
    Start --> Enterprise{Enterprise SSO?}
    Enterprise -->|Yes| Protocol{Protocol?}
    Enterprise -->|No| Security
    
    Protocol -->|SAML| SAML[SAML SSO]
    Protocol -->|OIDC| OIDC[Social Login/OIDC]
    
    Start --> Social{Social Login?}
    Social -->|Yes| OIDC
    Social -->|No| DeviceType

Recommendations by Industry

Industry	Recommended Flow	Rationale
Finance/Banking	WebAuthn + CIBA	Maximum security, regulatory compliance
Healthcare	WebAuthn + TOTP	HIPAA compliance, strong authentication
E-Commerce	Basic + Optional TOTP	Balance security and user experience
SaaS B2B	SAML SSO + MFA	Enterprise SSO requirements
Consumer Apps	Social Login + SMS	Reduce friction, quick onboarding
IoT/Smart Home	Device Authorization	Limited input capabilities
Call Centers	Voice Biometrics	Hands-free, phone-based

Combining Multiple Methods

You can layer authentication methods for enhanced security:

Example: Adaptive Authentication

# Start with basic login
basic_auth_result = authenticate_basic(username, password)

# Require MFA based on risk
if risk_score > threshold:
    mfa_result = require_webauthn(user_id)
elif user.mfa_enrolled:
    mfa_result = require_totp(user_id)

# Issue token after all checks pass
token = generate_token(user_id)

Next Steps

• Implement Basic Auth: User Management - Authentication
• Add MFA: Multi-Factor Authentication
• Enterprise SSO: OIDC & SAML
• API Patterns: API Conventions

---

Need help choosing? Review API Conventions for implementation patterns →