Ticket-Based Access

Relevant source files

The following files were used as context for generating this wiki page:

• warpgate-db-entities/src/Ticket.rs
• warpgate-web/src/admin/config/Tickets.svelte
• warpgate-admin/src/api/tickets_list.rs
• warpgate-core/src/config_providers/mod.rs
• warpgate-db-migrations/src/m00001_create_ticket.rs
• warpgate-protocol-http/src/middleware/ticket.rs
• warpgate-protocol-postgres/src/session.rs
• warpgate-web/src/admin/CreateTicket.svelte

Ticket-Based Access is a mechanism in Warpgate that allows users to bypass standard multi-step authentication by using a pre-generated secret key. These "tickets" are associated with a specific user and a specific target, enabling direct access to SSH, HTTPS, MySQL, or PostgreSQL targets without requiring additional interactive credentials at the time of connection.

Tickets are designed for temporary or automated access, featuring configurable expiration dates and a limited number of uses. Once a ticket is consumed or expired, it is no longer valid for authentication.

Sources: README.md, warpgate-web/src/admin/config/Tickets.svelte:78-79

Core Components and Data Model

The ticket system is built upon a database entity that tracks the lifecycle and constraints of each access secret.

Ticket Entity Schema

Each ticket is stored in the tickets table with the following attributes:

Field	Type	Description
id	Uuid	Unique identifier for the ticket.
secret	String	The hashed or plain secret key used for authentication.
username	String	The Warpgate user authorized by this ticket.
target	String	The specific target name the ticket grants access to.
uses_left	Option<i16>	Remaining number of times the ticket can be used.
expiry	Option<DateTime>	Absolute timestamp after which the ticket is invalid.
created	DateTime	Timestamp of ticket creation.

Sources: warpgate-db-migrations/src/m00001_create_ticket.rs:11-20, warpgate-admin/src/api/tickets_list.rs:88-97

Entity Relationships

The following diagram illustrates how tickets relate to users and targets within the Warpgate architecture.

Ticket Lifecycle Management

Creation

Tickets are created via the Admin Web UI or the Admin API. During creation, the administrator selects a target and a user, and optionally sets usage limits.

Validation and Consumption

When a connection is initiated using a ticket, Warpgate performs a series of checks:

1. Lookup: Finds the ticket by the provided secret string.
2. Usage Check: Verifies if uses_left is greater than zero (if set).
3. Expiry Check: Verifies if the current time is before the expiry timestamp (if set).
4. Consumption: If valid, the system decrements uses_left.

Sources: warpgate-core/src/config_providers/mod.rs:82-129

Protocol-Specific Implementation

HTTP Middleware

For HTTPS targets, tickets can be provided via a query parameter (warpgate-ticket) or a custom Authorization header.

Database Protocols (PostgreSQL)

In PostgreSQL sessions, tickets are handled during the startup phase. If the username follows the ticket selector format, the system validates the ticket secret provided (often in place of a password).

Protocol	Identification Method
PostgreSQL	AuthSelector::Ticket { secret }
HTTP	Authorization: Warpgate <secret> or ?warpgate-ticket=<secret>

Sources: warpgate-protocol-postgres/src/session.rs:182-200, warpgate-protocol-http/src/middleware/ticket.rs:56-65

Security Considerations

• One-Time Visibility: The plain-text secret key is only displayed to the administrator immediately after creation. It is stored in the database in a way that allows subsequent validation but prevents administrative recovery.
• Automatic Cleanup: Tickets are effectively disabled once their usage count reaches zero or their expiry time passes.
• Scope Limitation: Each ticket is hard-bound to exactly one user and one target, preventing lateral movement if a ticket is compromised.

Sources: warpgate-web/src/admin/CreateTicket.svelte:66-68, warpgate-core/src/config_providers/mod.rs:95-107