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

> Easily configure OpenID Connect SSO in Vaultwarden with our comprehensive guide. Integrate any OIDC provider using simple environment variables for secure access.

- Repository: [Daniel García/vaultwarden](https://github.com/dani-garcia/vaultwarden)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/config.rs))

All SSO settings are parsed from environment variables in [`src/config.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/sso_client.rs))

The [`src/sso_client.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/sso.rs))

The HTTP handlers in [`src/sso.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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

```text

# 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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/sso.rs) and [`src/sso_client.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/src/sso.rs) and verifies it during the token exchange in [`src/sso_client.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/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`](https://github.com/dani-garcia/vaultwarden/blob/main/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.