Authentication State Store
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication State Store is a central component in Warpgate responsible for managing the lifecycle and persistence of multi-step authentication processes. It tracks the progress of user authentication across various protocols (HTTP, SSH, MySQL, PostgreSQL), maintaining stateful information such as valid credentials provided so far and the remaining requirements needed to achieve a "Success" state.
This system is critical for supporting complex authentication flows, including Multi-Factor Authentication (MFA), Single Sign-On (SSO), and out-of-band approvals. By decoupling the authentication state from the immediate network connection, Warpgate allows users to perform actions like approving a login request via a separate web interface while the original protocol session remains pending.
Sources: warpgate-protocol-http/src/common.rs:219-250, warpgate-protocol-http/src/api/auth.rs:114-140
Core Architecture and Data Flow
The store functions as a registry for AuthState objects, which are identified by a unique Uuid. Each AuthState encapsulates the current progress of an authentication attempt for a specific user and protocol.
Authentication State Lifecycle
When a user initiates a connection, the protocol handler requests an authentication state from the store. If an existing state is found in the session (via AUTH_STATE_ID_SESSION_KEY), it is reused; otherwise, a new state is created.
AuthState Components
An AuthState tracks several key attributes during its lifetime:
- Identification String: A user-friendly string used to verify out-of-band requests.
- Valid Credentials: A list of
AuthCredentialobjects (e.g., Password, OTP, SSO) already verified by the system. - Protocol: The protocol initiating the request (e.g., "HTTP", "PostgreSQL").
- Verification Status: Computed via
state.verify(), returning anAuthResult(Accepted, Rejected, or Need).
Sources: warpgate-protocol-http/src/api/auth.rs:43-64, warpgate-protocol-http/src/api/auth.rs:328-344
Protocol Integration
The Authentication State Store is utilized differently depending on the protocol requirements.
HTTP Authentication
In the HTTP protocol, the state is often tied to the web session. The get_auth_state_for_request function manages the retrieval or creation of these states within a poem::session::Session.
Sources: warpgate-protocol-http/src/common.rs:219-230
PostgreSQL Authentication
For database protocols like PostgreSQL, the session handler creates an authentication state to validate cleartext passwords or tickets.
Authentication States and Results
The system maps internal authentication logic to API-visible states used by the web interface to guide the user.
API Auth States
| State | Description |
|---|---|
NotStarted | Initial state before credentials are provided. |
PasswordNeeded | The policy requires a password credential. |
OtpNeeded | The policy requires a One-Time Password (TOTP). |
SsoNeeded | Single Sign-On interaction is required. |
WebUserApprovalNeeded | Waiting for the user to click "Approve" in the web UI. |
PublicKeyNeeded | SSH Public Key authentication is required. |
Success | All policy requirements met. |
Failed | Authentication was explicitly rejected or failed. |
Sources: warpgate-protocol-http/src/api/auth.rs:21-41, warpgate-protocol-http/src/api/auth.rs:80-100
Out-of-Band (OOB) Approvals
One of the primary uses of the state store is managing OOB approvals. A user might connect via SSH (which enters a WebUserApprovalNeeded state) and then log into the Warpgate web portal to approve that specific session.
Approval Flow
- Request: The protocol handler creates an
AuthStatewith anidentification_string. - Display: The web UI fetches the state by ID and displays the security key to the user.
- Approval: The user clicks "Authorize" in the UI, which calls the
/auth/state/:id/approveendpoint. - Resumption: The protocol handler, watching the
AuthState, sees the newAuthCredential::WebUserApprovaland proceeds.
Sources: warpgate-web/src/gateway/OutOfBandAuth.svelte:53-65, warpgate-protocol-http/src/api/auth.rs:279-301
Implementation Details
Configuration and Setup
During initial warpgate setup, a built-in admin user is created with a password credential. This initial state is stored in the underlying database, which the ConfigProvider uses to validate credentials added to the AuthState.
Sources: warpgate/src/commands/setup.rs:245-285, warpgate-core/src/config_providers/db.rs:200-240
Security and Cleanup
- Session Linking: HTTP sessions track their
auth_state_idto prevent session fixation and ensure state continuity. - Completion: Once authentication is successful, the state is marked as complete via
store.complete(id)to prevent reuse of temporary authentication data. - Rejection: If a user cancels or an error occurs,
store.completeis called after callingstate.reject()to invalidate the attempt.
Sources: warpgate-protocol-http/src/common.rs:220-225, warpgate-protocol-http/src/api/auth.rs:268-275
Summary
The Authentication State Store acts as the "brain" for Warpgate's multi-step authentication. By providing a centralized, thread-safe, and ID-addressable store for authentication progress, it enables modern security features like MFA and out-of-band approvals across legacy protocols like SSH and SQL.