SSO / SAML

Active contributors: auth team.

Purpose

Bitwarden's enterprise customers can require their members to sign in with the company's SSO IdP. The flow is conceptually:

1. The user clicks "Continue with SSO" in the web vault.
2. The web vault redirects to Identity with grant_type=sso (deferred — first the user has to actually log in via SSO).
3. Identity redirects to the Sso host, which figures out the user's organization, looks up the SSO config, and redirects to the customer IdP (SAML 2.0 or OIDC).
4. The IdP returns the assertion / id-token.
5. Sso mints a one-shot SsoTokenable and redirects back to Identity.
6. Identity consumes the tokenable via SsoExtensionGrantValidator and issues a Bitwarden access + refresh token.

If the org has the RequireSso policy on, master-password login is blocked for that org's members.

Where the code lives

Concern	Path
Sso host	bitwarden_license/src/Sso/ (see apps/sso)
Identity host bridge	src/Identity/Startup.cs (AddOpenIdConnect("sso", ...))
SSO domain	src/Core/Auth/Sso/, src/Core/Auth/Entities/SsoConfig.cs, SsoUser.cs
Tokenable	src/Core/Auth/Models/Business/Tokenables/SsoTokenable.cs
Grant validator	src/Core/Auth/IdentityServer/RequestValidators/SsoExtensionGrantValidator.cs
Web admin config	src/Api/AdminConsole/Controllers/SsoConfigsController.cs
Schema	src/Sql/dbo/Tables/SsoConfig.sql, SsoUser.sql

Key abstractions

Type	Description
SsoConfig	Per-organization SSO configuration (protocol, IdP entity-id, signing certs, claim mapping). Stored encrypted with data protection.
SsoUser	A confirmed mapping between an Organization member and a unique IdP claim (SsoUser.ExternalId). Created on first successful SSO login.
SsoTokenable	Signed payload Sso emits with the user id, org id, and an expiration. The only way Identity knows the customer IdP authenticated this user.
SsoExtensionGrantValidator	Validates the tokenable, checks the Identity-side org membership, applies the RequireSso policy, and produces the access token.
RequireSsoPolicyValidator	(src/Core/AdminConsole/OrganizationFeatures/Policies/PolicyValidators/RequireSsoPolicyRequirement.cs) — gates master-password login when the org enforces SSO.

How it works

sequenceDiagram
    participant Web
    participant Id as Identity
    participant SSO as Sso host
    participant IdP as Customer IdP
    participant Db

    Web->>Id: GET /sso/start?orgId=…
    Id->>SSO: redirect (OIDC challenge)
    SSO->>Db: load SsoConfig for org
    SSO->>IdP: SAML AuthnRequest / OIDC redirect
    IdP-->>SSO: SAML Response / id_token
    SSO->>SSO: map claims, ensure SsoUser
    SSO->>Id: redirect with SsoTokenable
    Web->>Id: POST /connect/token (grant=sso, code=tokenable)
    Id->>Db: SsoExtensionGrantValidator validates
    Id->>Db: enforce RequireSso policy
    Id-->>Web: access_token + refresh_token + userDecryptionOptions

If the user is not yet an OrganizationUser, the flow can also create / accept the membership automatically based on SsoConfig settings (AutomaticInvite etc.).

SAML / OIDC libraries

• SAML — Sustainsys.Saml2.AspNetCore2 (currently 2.11.0, bumped in PR #6207, 2025-10-08).
• OIDC — Microsoft's Microsoft.AspNetCore.Authentication.OpenIdConnect registered in bitwarden_license/src/Sso/Startup.cs.

The shared SAML / OIDC option builders that map SsoConfig to handler options live in bitwarden_license/src/Sso/Utilities/.

Self-host

A self-hosted enterprise customer can run Sso as part of the bundled stack. Configuration is per-organization, edited in the Web Vault Admin Console UI; the Api host writes the encrypted SsoConfig row.

Trusted Device Encryption

For SSO-only orgs that do not want users to remember a master password, the Trusted Device Encryption (TDE) flow ships the wrapped user key on a per-device basis. See auth.md and src/Core/Auth/UserFeatures/DeviceTrust/. The TDE off-boarding path lets a user opt back into a master password later; the related code lives under src/Core/Auth/UserFeatures/TdeOffboardingPassword/.

Entry points for modification

• Adding support for a new SAML profile or NameID format → extend bitwarden_license/src/Sso/Utilities/Saml2OptionsBuilder.cs.
• Tightening the SSO callback → SsoExtensionGrantValidator and Sso/Controllers/AccountController.cs.
• New per-org SSO setting → extend SsoConfig (and the encrypted-payload model SsoConfigurationData) plus the Admin Console UI.
• Changing RequireSso enforcement → RequireSsoPolicyValidator.