OTP & Multi-Factor Auth
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate implements One-Time Password (OTP) and Multi-Factor Authentication (MFA) as a core security layer to protect access to SSH, HTTPS, MySQL, and PostgreSQL targets. The system primarily utilizes Time-based One-Time Passwords (TOTP) following RFC 4648 for secret encoding and RFC 6238 for token generation. Users can manage their own OTP devices via the gateway interface, while administrators can enforce multi-factor policies globally or per-protocol.
Sources: README.md:14-22, warpgate-web/src/admin/CreateOtpModal.svelte:44-55
TOTP Implementation & Registration
The TOTP mechanism in Warpgate uses 6-digit tokens with a 30-second period and the SHA1 algorithm. During registration, the system generates a random 32-byte secret key which is presented to the user as a Base32-encoded string and a QR code for easy enrollment in authenticator apps.
Registration Flow
The enrollment process requires the user to validate a generated token before the secret is saved to the database. This ensures that the client application is correctly synchronized with the server's time and algorithm settings.
The registration component utilizes the otpauth library for client-side generation and qrcode for visual display.
Sources: warpgate-web/src/admin/CreateOtpModal.svelte:36-95, warpgate-admin/src/api/otp_credentials.rs:90-104
Authentication Policies
Warpgate allows for granular control over when MFA is required. Policies can be defined per protocol (SSH, HTTP, MySQL, PostgreSQL) and can require combinations of credentials, such as a Public Key AND a TOTP token.
Credential Types
The system supports several credential "kinds" that can be combined in a policy:
| Credential Kind | Description |
|---|---|
Password | Standard alphanumeric password string |
PublicKey | SSH Public Key (RSA, Ed25519, etc.) |
Totp | Time-based One-Time Password token |
Sso | Single Sign-On (OpenID Connect) |
WebUserApproval | Out-of-band approval via web interface |
Sources: warpgate-web/src/gateway/lib/openapi-schema.json:490-500, warpgate-core/src/config_providers/db.rs:114-160
Policy Logic
When a user attempts to authenticate, the DatabaseConfigProvider evaluates the UserRequireCredentialsPolicy. If a TOTP device is registered and the policy for the specific protocol includes Totp, the authentication state transitions to OtpNeeded.
Backend Architecture
OTP credentials are treated as distinct entities in the database, linked to a specific user ID.
Data Model: OtpCredential
Stored in the otp_credentials table, the model includes:
id: A unique UUID for the credential record.user_id: UUID linking the device to a specific user.key: The raw bytes of the TOTP secret key (stored as a secret/sensitive value).
Sources: warpgate-admin/src/api/otp_credentials.rs:19-35, warpgate-core/src/config_providers/db.rs:248-250
API Endpoints
The Admin and Gateway APIs provide endpoints for managing these credentials:
| Method | Endpoint | Description |
|---|---|---|
GET | /profile/credentials | Retrieves current user's credential state |
POST | /profile/credentials/otp | Adds a new OTP device for the current user |
DELETE | /profile/credentials/otp/{id} | Removes an OTP device |
POST | /auth/otp | Submits a TOTP token during the login flow |
Sources: warpgate-web/src/gateway/lib/openapi-schema.json:255-320
Management Interface
Users can manage their own OTP devices through the "Credential Manager" in the gateway UI. If a user's policy requires TOTP but no device is registered, the UI displays a warning. Administrators can also add or delete OTP credentials for any user via the Admin UI's "Credential Editor".
Implementation Details
- Auto-Policy Assignment: When an administrator adds an OTP device to a user who already has a password or public key, Warpgate automatically suggests or applies a 2FA policy (e.g.,
[Password, Totp]) for HTTP and SSH protocols. - Verification: The
verify_totphelper inwarpgate-commonis used by the backend to validate tokens against stored secrets.
Sources: warpgate-web/src/gateway/CredentialManager.svelte:95-115, warpgate-web/src/admin/CredentialEditor.svelte:105-125, warpgate-core/src/config_providers/db.rs:252-255
Conclusion
The OTP & MFA system in Warpgate provides a robust second layer of security by integrating standard TOTP protocols into its multi-protocol proxy architecture. By allowing flexible policy definitions per user and per protocol, it ensures that sensitive targets (like SSH or Database access) can be protected with higher levels of assurance than standard password-based authentication.