Single Sign-On (OIDC)
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate provides native support for Single Sign-On (SSO) using the OpenID Connect (OIDC) protocol. This system allows users to authenticate against external identity providers (IdPs) such as Google, Apple, and Microsoft Azure, or any custom OIDC-compliant server. The SSO integration handles user authentication, automatic user provisioning, and role synchronization based on provider claims.
Sources: README.md:16, warpgate-sso/src/config.rs:43-69
SSO Architecture and Components
The SSO implementation is divided into configuration, client logic, and protocol-specific API handlers.
Provider Configuration
Warpgate supports several internal provider types, each with specific configuration requirements:
- Google: Uses the standard Google issuer URL.
- Apple: Requires
key_idandteam_idfor client secret generation via ES256 signing. - Azure: Requires a
tenantID to construct the Microsoft v2.0 endpoint. - Custom: Allows full specification of
issuer_url,scopes, androle_mappings.
Sources: warpgate-sso/src/config.rs:43-69, warpgate-sso/src/config.rs:141-163
Logical Flow of SSO Authentication
The following sequence diagram illustrates the interaction between the User, Warpgate (acting as the OIDC client), and the external Identity Provider.
The authentication flow uses the standard Authorization Code flow, incorporating PKCE (Proof Key for Code Exchange) where supported by the provider.
Sources: warpgate-sso/src/sso.rs:107-130, warpgate-protocol-http/src/api/sso_provider_list.rs:159-223
Key Data Structures
SsoProviderConfig
Defines how an SSO provider is represented in the Warpgate configuration.
| Field | Type | Description |
|---|---|---|
name | String | Unique internal identifier for the provider. |
label | Option<String> | Display name used in the UI. |
provider | Enum | The internal provider configuration (Google, Apple, etc.). |
auto_create_users | Boolean | Whether to automatically create a Warpgate user upon successful login. |
Sources: warpgate-sso/src/config.rs:24-33
Auth States and Credentials
SSO is treated as a valid credential type within the AuthCredential enum. When a user authenticates via SSO, the system validates the email and provider against existing SsoCredential records in the database.
Sources: warpgate-core/src/config_providers/db.rs:220-244, warpgate-web/src/gateway/lib/openapi-schema.json:1010-1025
Role Mapping and User Provisioning
Warpgate can automatically manage user roles based on claims received from the OIDC provider, specifically using the warpgate_roles claim or custom group mappings.
Auto-creation Logic
If auto_create_users is enabled, Warpgate will create a new user record if a matching email is not found during login. It utilizes the preferred_username claim provided by the IdP for the new account's username.
Sources: warpgate-core/src/config_providers/db.rs:43-70, warpgate-core/src/config_providers/db.rs:172-185
Role Synchronization
Role synchronization occurs during the final phase of the login process. The system retrieves remote groups from the IdP response and applies them based on a role_mappings hash map.
API Endpoints
The following endpoints manage the SSO lifecycle within the HTTP protocol:
| Endpoint | Method | Operation ID | Description |
|---|---|---|---|
/sso/providers | GET | get_sso_providers | Lists all configured SSO providers. |
/sso/providers/{name}/start | GET | start_sso | Initiates the OIDC flow for a specific provider. |
/sso/return | GET/POST | return_to_sso | Callback URL for the IdP to return the authorization code. |
/sso/logout | GET | initiate_sso_logout | Starts the Single Log Out (SLO) process. |
Sources: warpgate-web/src/gateway/lib/openapi-schema.json:285-360, warpgate-protocol-http/src/api/sso_provider_list.rs:88-157
Single Logout (SLO)
If the provider metadata includes an end_session_endpoint, Warpgate supports Single Logout. This allows the user to be logged out of the identity provider simultaneously when ending their Warpgate session. The SsoClient checks for this capability via supports_single_logout.
Sources: warpgate-sso/src/sso.rs:99-105, warpgate-protocol-http/src/api/sso_provider_list.rs:268-297
Implementation Details
SSO Credential Validation
In the database config provider, SSO credentials are validated by matching the provider name and the verified email address.
AuthCredential::Sso {
provider: client_provider,
email: client_email,
} => {
for credential in user_details.credentials.iter() {
if let UserAuthCredential::Sso(UserSsoCredential {
ref provider,
ref email,
}) = credential
{
if provider.as_ref().unwrap_or(client_provider) == client_provider
&& email == client_email
{
return Ok(true);
}
}
}
Ok(false)
}
Sources: warpgate-core/src/config_providers/db.rs:232-249
Web Admin Integration
Administrators can manually associate OIDC identities with users through the Credential Editor in the web UI. This allows for pre-provisioning accounts or linking existing accounts to multiple SSO identities.
Sources: warpgate-web/src/admin/CredentialEditor.svelte:145-167