User Journey

What a person and your application each do, from the login button to a session.

sequenceDiagram
    participant User
    participant Client as Client Application
    participant TV as TrueVault OAuth Server
    participant BARIC as BARIC Identity Verification

    Note over User,BARIC: 1. Authorization Request
    User ->>  Client: Click "Login with TrueVault"
    Client ->>  Client: Generate PKCE (code_verifier, code_challenge)
    Client ->>  Client: Generate state & nonce
    Client ->>  User: Redirect to TrueVault authorize endpoint
    User ->>  TV: GET /oauth/oidc/authorize (client_id, redirect_uri, scope, state, code_challenge, nonce)

    Note over TV,BARIC: 2. Identity Verification
    TV ->>  TV: Validate client & parameters
    TV ->>  TV: Create identity sharing request
    TV ->>  User: Redirect to identity flow
    User ->>  BARIC: Complete identity verification (document upload, biometric checks)
    BARIC ->>  BARIC: Verify identity against ruleset
    BARIC ->>  User: Request consent to share data
    User ->>  BARIC: Grant consent
    BARIC ->>  TV: Return to authorization flow

    Note over TV,Client: 3. Authorization Response
    TV ->>  TV: Generate authorization code
    TV ->>  User: Redirect to client callback
    User ->>  Client: GET /callback?code=AUTH_CODE&state=STATE
    Client ->>  Client: Validate state parameter
    Client ->> Client: Validate state parameter

    Note over Client,TV: 4. Token Exchange
    Client ->> TV: POST /oauth/oidc/token (code, client_id, client_secret, code_verifier, redirect_uri)
    TV ->> TV: Validate authorization code
    TV ->> TV: Verify PKCE (code_verifier)
    TV ->> TV: Generate access_token, id_token, refresh_token
    TV ->> Client: Return tokens (access_token, id_token, refresh_token)
    Client ->> Client: Validate & decode id_token (verify signature, nonce)

    Note over Client,TV: 5. UserInfo Request
    Client ->> TV: GET /oauth/oidc/userinfo Authorization: Bearer ACCESS_TOKEN
    TV ->> TV: Validate access token
    TV ->> TV: Retrieve user claims based on scope
    TV ->> Client: Return user information (sub, name, email, verified claims)

    Note over Client,User: 6. Session Creation
    Client ->> Client: Create user session
    Client ->> User: Login successful, redirect to app

    Note over Client,TV: 7. Token Refresh (Optional)
    Client ->> TV: POST /oauth/oidc/token (grant_type=refresh_token, refresh_token, client_id, client_secret)
    TV ->> TV: Validate refresh token
    TV ->> Client: Return new access_token & refresh_token

This illustrates a new user, completing an identity for the first time.