Authentication & RBAC Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate implements a multi-protocol authentication system and Role-Based Access Control (RBAC) to manage access to SSH, HTTPS, MySQL, and PostgreSQL targets. The architecture centers around a flexible credential policy engine that allows per-user and per-protocol requirements, coupled with a role-based mapping system that connects authenticated users to specific target resources.
Sources: README.md, warpgate-core/src/config_providers/db.rs
Authentication Flow and Lifecycle
Authentication in Warpgate is handled through a sequence of credential validation and state tracking. When a client connects, the system identifies the user and target via an AuthSelector and then initiates a session-specific AuthState.
Auth States and Selectors
The AuthSelector parses connection strings (such as SSH usernames or database usernames) to determine the intended user and target. It supports two primary modes:
- Standard User: Format
user#target, identifying both the Warpgate user and the destination. - Ticket: Format
ticket#secret, using a pre-generated temporary credential.
The AuthState tracks the progress of multi-factor authentication, maintaining a list of valid credentials provided by the client until the requirements of the CredentialPolicy are met.
Sources: warpgate-common/src/auth/selector.rs, warpgate-common/src/auth/state.rs, warpgate-protocol-postgres/src/session.rs:133-150
Credential Policy Engine
Warpgate employs a granular policy engine to enforce which credentials are required for successful authentication. Policies can be defined globally for a user or overridden for specific protocols.
Supported Credential Types
The system validates several types of credentials:
- Password: Verified against Argon2 hashes stored in the database.
- PublicKey: Standard OpenSSH public keys.
- OTP (TOTP): Time-based one-time passwords for 2FA.
- SSO (OIDC): External identity provider authentication.
Sources: warpgate-core/src/config_providers/db.rs:197-250, warpgate-protocol-http/src/api/credentials.rs
Policy Implementation
The DatabaseConfigProvider constructs a CredentialPolicy by combining user settings and protocol constraints. A PerProtocolCredentialPolicy can enforce different rules (e.g., SSH requires Public Key + OTP, while HTTP only requires Password).
Sources: warpgate-core/src/config_providers/db.rs:90-140
| Policy Component | Description |
|---|---|
AnySingleCredentialPolicy | Satisfied by any one supported credential type. |
AllCredentialsPolicy | Requires a specific set of credential types to be present. |
PerProtocolCredentialPolicy | Maps specific protocols (SSH, HTTP, etc.) to different sub-policies. |
Sources: warpgate-core/src/config_providers/db.rs:105-135
Role-Based Access Control (RBAC)
RBAC in Warpgate is the bridge between an authenticated user and an authorized target. Access is granted if a user shares at least one role with the target.
User and Role Management
Users and Roles are managed via the Admin API. Relationships are stored in a UserRoleAssignment table.
- Users: Entities that can authenticate.
- Roles: Logical groupings of permissions.
- Targets: Remote hosts or services (SSH, Web, DB) protected by Warpgate.
Sources: warpgate-admin/src/api/users.rs, warpgate-admin/src/api/roles.rs
Target Authorization Logic
The authorization check happens after a successful authentication. The system retrieves the roles assigned to the user and the roles required by the target. If the intersection of these sets is non-empty, access is granted.
Admin Role
The system includes a built-in admin role (warpgate:admin). Users with this role (or users who can authorize against a target with TargetOptions::WebAdmin) are granted access to administrative APIs and the web UI.
Sources: warpgate-core/src/commands/setup.rs:253-260, warpgate-protocol-http/src/common.rs:135-155
API Security
The administrative and profile APIs use security schemes to ensure only authorized requests are processed.
| Security Scheme | Description |
|---|---|
| Session-based | Uses HTTP cookies (warpgate-http-session) for web UI access. |
| API Token | Uses the x-warpgate-token header for programmatic access, validated against ApiToken entries. |
| Admin Token | A static token defined in configuration for initial setup/automation. |
Sources: warpgate-protocol-http/src/common.rs:25-45, warpgate-protocol-http/src/common.rs:175-195
Implementation Detail: HTTP Auth Middleware
The HTTP protocol implementation uses "around" endpoints to wrap logic with authentication checks. endpoint_admin_auth specifically checks if the requesting user has access to the Web Admin target.
Sources: warpgate-protocol-http/src/common.rs:160-170
SSO and User Auto-Provisioning
When Single Sign-On (SSO) is enabled, Warpgate can automatically create user accounts and map roles based on claims from the OIDC provider.
- User Matching: The system attempts to match the OIDC email and provider to an existing
SsoCredential. - Auto-creation: If
auto_create_usersis enabled in the SSO config, a new user is created upon the first successful login. - Role Mapping: The
apply_sso_role_mappingsfunction synchronizes user roles with those provided by the SSO provider during the login flow.
Sources: warpgate-core/src/config_providers/db.rs:150-170, warpgate-core/src/config_providers/db.rs:320-370
Summary
The Authentication & RBAC Architecture of Warpgate provides a robust, multi-layered security model. By abstracting authentication into AuthState and CredentialPolicy, Warpgate supports complex 2FA scenarios across multiple protocols. The RBAC system ensures that once a user is identified, their access is strictly limited to the targets defined by their assigned roles, with a specialized path for administrative access via the Web UI.