Compass: Authentication Flow Engine

Compass records each authentication attempt as a flow: a sequence of named steps, each with its own outcome, duration, and error details. It is how you find out where a login actually went wrong.

Why

From outside, authentication is one request and one token. Inside, it is redirect validation, credential hashing, an MFA challenge, maybe an external IdP round trip, session creation, and token signing. When it fails, 401 tells you nothing about which of those broke.

With Compass you get this instead:

How it works

With Compass on, every authentication request opens a CompassFlow. As the request moves through credential validation, the MFA challenge, token exchange, and finalization, each step is written as a CompassFlowStep with its own status and duration.

graph TD
    A[Flow Started] --> B[Authorize]
    B --> C[Credential Validation]
    C --> D{MFA Required?}
    D -->|Yes| E[MFA Challenge]
    D -->|No| F[Token Exchange]
    E --> F
    F --> G[Finalize]
    G --> H[Flow Completed]

Flow lifecycle

Flow structure

A CompassFlow holds the whole attempt:

Flow status values

Flow steps

Each step records:

Step types

Step status values

Configuration

Turn it off and authentication behaves identically, minus the recording: no flows, no steps, no database writes. Worth doing on realms where you do not need step-level observability.