Identity & Login Model

Responsibility View

This document explains how identity and authentication work end-to-end. It answers the question: How does a user gain access to a service?

Authentication Flow

The following diagram illustrates the branching logic for user authentication, including session persistence and MFA requirements.

flowchart TD
    Start([User visits service.risu.tech]) --> Ingress[Ingress / Auth Proxy]
    Ingress --> CheckAppSession{Valid Session?}
    
    CheckAppSession -- "Yes" --> Forward[Forward to App]
    CheckAppSession -- "No" --> IdP[Redirect to Identity Provider]
    
    subgraph IdPFlow [Identity Provider]
        IdP --> CheckIdPSession{IdP Session exists?}
        CheckIdPSession -- "No" --> Login[User Credentials Prompt]
        Login --> Validate[Validate Credentials]
        Validate -- "Success" --> CheckMFA{MFA required?}
        Validate -- "Failure" --> Login
        
        CheckIdPSession -- "Yes" --> CheckMFA
        
        CheckMFA -- "Yes" --> MFAPrompt[MFA Challenge]
        MFAPrompt --> ValidateMFA[Validate MFA]
        ValidateMFA -- "Success" --> Authorize[Authorize Access]
        ValidateMFA -- "Failure" --> MFAPrompt
        
        CheckMFA -- "No" --> Authorize
    end
    
    Authorize --> Grant[Redirect with Session Cookie]
    Grant --> Ingress
    
    Forward --> Service[App Content]
    Service --> End([Success])

Functional Components

Auth Proxy / Ingress

The first line of defense. It intercepts requests and verifies the presence of a valid session cookie. If missing or expired, it handles the OIDC/SAML handshake with the IdP.

Identity Provider (IdP)

The source of truth for user accounts and groups. It manages credentials, MFA enrollment, and issues tokens upon successful authentication.

Application (Service)

The destination. Most applications are “auth-blind,” relying on the Auth Proxy to provide user information via headers (e.g., X-Forwarded-User).