How to Set Up OpenID Connect SSO in Vaultwarden: Complete Configuration Guide

Vaultwarden implements a generic OpenID Connect (OIDC) client that works with any compliant identity provider by discovering endpoints from a .well-known/openid-configuration URL, requiring only environment variables to enable SSO without provider-specific code changes.

Vaultwarden, the open-source Bitwarden-compatible password server written in Rust, supports enterprise Single Sign-On through the OpenID Connect Core specification. By leveraging the discovery mechanism defined in OIDC 1.0, the implementation in dani-garcia/vaultwarden remains provider-agnostic while supporting major identity platforms like Google Workspace, Microsoft Azure AD, and Keycloak. This guide walks through the architecture, supported providers, and exact configuration steps using the SSO_* environment variables defined in the source code.

Architecture of Vaultwarden’s OIDC Implementation

The SSO implementation spans four core components that handle discovery, session management, and token validation without hardcoding provider logic.

Configuration Layer (src/config.rs)

All SSO settings are parsed from environment variables in src/config.rs (lines 998–1032). The configuration block defines options including sso_enabled, sso_client_id, sso_authority, sso_scopes, and PKCE settings. These values are exposed through the global CONFIG struct and consumed by the authentication handlers.

Discovery and Caching (src/sso_client.rs)

The src/sso_client.rs file (lines 45–99) builds an openidconnect::Client by performing discovery against the sso_authority URL. The client fetches the provider’s .well-known/openid-configuration document to obtain authorization and token endpoints dynamically. To reduce overhead, Vaultwarden caches this metadata using mini-moka according to the sso_client_cache_expiration setting. This module also handles token exchange, ID-token validation, and optional debug logging when SSO_DEBUG_TOKENS is enabled.

Authentication Flow (src/sso.rs)

The HTTP handlers in src/sso.rs (lines 84–115) orchestrate the Authorization Code flow:

1. State generation – Creates a base64-encoded state value containing the organization identifier.
2. Authorization URL construction – Uses discovered endpoints, configured scopes, and optional PKCE challenge (sso_pkce) to build the redirect URL.
3. Callback handling – Validates the returned state, verifies the PKCE verifier if used, exchanges the authorization code for tokens, and creates an internal Vaultwarden session JWT via encode_ssotoken_claims.
4. Persistence – Stores the correlation between the Vaultwarden user and the external OIDC subject (sub) in the sso_auth table defined in src/db/models/sso_auth.rs.

Supported Identity Providers

Because Vaultwarden relies solely on the OIDC discovery endpoint ({authority}/.well-known/openid-configuration), any provider compliant with OpenID Connect 1.0 works without code modifications. Commonly deployed providers include:

• Google Workspace – https://accounts.google.com
• Microsoft Azure AD – https://login.microsoftonline.com/<tenant-id>/v2.0
• Auth0 – https://<your-domain>.auth0.com
• Keycloak – https://<host>/auth/realms/<realm>
• Okta – https://<your-okta-domain>.okta.com/oauth2/default
• GitLab – https://gitlab.com
• FusionAuth – https://<host>/oauth2
• OneLogin – https://<domain>.onelogin.com/oidc/2
• Ping Identity – https://<host>/as

GitHub requires special handling via SSO_AUTHORIZE_EXTRA_PARAMS to request offline access, as it implements OIDC partially through GitHub Apps.

Step-by-Step Configuration Guide

Required Environment Variables

Set these variables in your .env file or Docker secrets to enable the OIDC integration:

1. Enable SSO – SSO_ENABLED=true
2. Set the authority – SSO_AUTHORITY must be the base URL without the /.well-known/openid-configuration suffix (e.g., https://accounts.google.com).
3. Provide credentials – SSO_CLIENT_ID and SSO_CLIENT_SECRET from your provider’s console.
4. Define scopes – SSO_SCOPES defaults to "email profile"; add offline_access for refresh tokens.

Optional Security Settings

• PKCE – Set SSO_PKCE=true to enable Proof Key for Code Exchange, recommended for public clients like mobile or desktop applications.
• Audience validation – Use SSO_AUDIENCE_TRUSTED to provide a regex whitelisting additional token audiences beyond the client ID.
• Extra parameters – Add SSO_AUTHORIZE_EXTRA_PARAMS="access_type=offline&prompt=consent" for Google to ensure refresh tokens are issued.
• Cache expiration – Set SSO_CLIENT_CACHE_EXPIRATION in seconds (default varies); use 0 to disable caching during development.
• Debug logging – Combine SSO_DEBUG_TOKENS=true with LOG_LEVEL=debug to log ID and access tokens.

Complete Configuration Example

# Enable OpenID Connect SSO

SSO_ENABLED=true

# Restrict login to SSO only (optional)

SSO_ONLY=false

# Provider discovery base URL (Google example)

SSO_AUTHORITY=https://accounts.google.com

# Scopes requested from the provider

SSO_SCOPES="email profile openid"

# Extra parameters to request a refresh token from Google

SSO_AUTHORIZE_EXTRA_PARAMS="access_type=offline&prompt=consent"

# Client credentials obtained from the provider console

SSO_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
SSO_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET

# Enable PKCE (recommended)

SSO_PKCE=true

# Cache discovery metadata for 10 minutes (600 seconds)

SSO_CLIENT_CACHE_EXPIRATION=600

# Log all tokens (only for debugging)

SSO_DEBUG_TOKENS=false

Troubleshooting Common OIDC Errors

Symptom	Likely Cause	Resolution
“Failed to discover OpenID provider”	Incorrect SSO_AUTHORITY including the discovery suffix or trailing slash	Use the base URL only, e.g., https://login.microsoftonline.com/<tenant-id>/v2.0 without /.well-known/openid-configuration.
“PKCE client challenge failed”	Provider does not support PKCE or method mismatch	Disable PKCE (SSO_PKCE=false) or verify the provider supports code_challenge_method=S256.
“Invalid Issuer for base token claim”	Provider’s issuer value differs from SSO_AUTHORITY	Set SSO_AUTHORITY to the exact issuer value returned in the discovery document (common with Azure AD).
No SSO button in web-vault	SSO_ENABLED=false or admin token missing	Enable SSO and ensure the admin page is accessible, or set DISABLE_ADMIN_TOKEN=true for testing.
Tokens not logged	Log level too high	Start with LOG_LEVEL=debug or LOG_LEVEL=info,vaultwarden::sso=debug.

Summary

• Vaultwarden’s OIDC implementation in src/sso.rs and src/sso_client.rs uses automatic discovery to support any compliant provider without custom code.
• Configuration requires only environment variables: SSO_ENABLED, SSO_AUTHORITY, SSO_CLIENT_ID, and SSO_CLIENT_SECRET.
• The system supports PKCE for enhanced security, token caching for performance, and debug logging for troubleshooting.
• Major providers like Google, Azure AD, Keycloak, and Okta are verified compatible through the standard discovery mechanism.

Frequently Asked Questions

What identity providers work with Vaultwarden SSO?

Any provider publishing a .well-known/openid-configuration document and supporting the Authorization Code flow works with Vaultwarden. This includes Google Workspace, Microsoft Azure AD, Auth0, Keycloak, Okta, GitLab, FusionAuth, OneLogin, and Ping Identity. The implementation automatically discovers endpoints from the SSO_AUTHORITY URL without requiring provider-specific code changes.

How do I enable PKCE for enhanced security?

Set the environment variable SSO_PKCE=true in your configuration. This enables Proof Key for Code Exchange, which protects against authorization code interception attacks and is required by some providers for public clients. When enabled, Vaultwarden generates a code challenge in src/sso.rs and verifies it during the token exchange in src/sso_client.rs.

Why is my SSO configuration failing with “Failed to discover OpenID provider”?

This error occurs when SSO_AUTHORITY contains the discovery path suffix or an incorrect base URL. The authority must be the root URL only (e.g., https://accounts.google.com), not https://accounts.google.com/.well-known/openid-configuration. Vaultwarden appends the discovery path automatically when fetching metadata in src/sso_client.rs.

Can I restrict Vaultwarden to SSO-only authentication?

Yes. Set SSO_ONLY=true to disable password-based logins and require all users to authenticate through the configured OIDC provider. When this is enabled, the standard login form is hidden and users are redirected immediately to the identity provider’s authorization endpoint defined in the discovery document.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}