Sso (commercial)

Active contributors: auth team.

Purpose

bitwarden_license/src/Sso/ is the SAML 2.0 / OIDC bridge between an enterprise customer's identity provider and Bitwarden's Identity host. It is a Razor + IdentityServer application that:

1. Acts as an OIDC provider to Identity — when Identity initiates sso authentication it redirects here.
2. Acts as a SAML / OIDC service provider outward — it then redirects the user to the customer's IdP, validates the assertion / id-token, and returns a one-shot SsoTokenable back to Identity so the user can complete the sso extension grant.

Because the project is part of the commercial license (not OSS), it lives in the bitwarden_license/ tree.

Directory layout

bitwarden_license/src/Sso/
├── Program.cs / Startup.cs
├── IdentityServer/                # Local IdentityServer config — issues "oidc-identity" id-tokens to Identity
├── Controllers/
│   ├── AccountController.cs       # /Account/Login (initiate), /Account/ExternalCallback (return), /Account/Logout
│   └── ...
├── Models/                        # ViewModels for SAML/OIDC config, SsoCallback, etc.
├── Utilities/                     # SAML/OIDC option builders
├── Views/                         # Razor views for "Choose your IdP" / error pages
├── Sass/                          # SCSS source compiled by webpack
├── package.json + webpack.config.js
├── appsettings.*.json
└── Dockerfile / build.sh / entrypoint.sh

The shared protocol code lives in src/Core/Auth/Sso/ (configuration entities, tokenable types) and in CODEOWNERS-shared src/Identity/IdentityServer/ (the sso external OIDC handler is registered there).

Key abstractions

Type	Path	Description
Startup	bitwarden_license/src/Sso/Startup.cs	Adds Sustainsys.Saml2 + OpenIdConnect handlers, registers IdentityServer with the oidc-identity client, wires Bitwarden services.
AccountController	bitwarden_license/src/Sso/Controllers/AccountController.cs	Coordinates the SAML / OIDC flow: figures out the org, redirects to the customer IdP, validates the response, builds the SsoTokenable, and redirects back to Identity.
SsoConfig (entity)	src/Core/Auth/Entities/SsoConfig.cs	Per-organization SSO configuration: protocol, IdP entity-id / metadata, claim mappings.
SsoTokenable	src/Core/Auth/Models/Business/Tokenables/SsoTokenable.cs	The one-shot signed token Sso emits; consumed by SsoExtensionGrantValidator in Identity.
Sustainsys.Saml2.AspNetCore2 (NuGet)	Saml2.cs registration in Startup	Provides the SAML SP endpoints (/saml2/Acs, /saml2/Logout). Currently bumped to 2.11.0 (PR #6207, 2025-10).

How it works

sequenceDiagram
    participant Web as Web Vault
    participant Id as Identity
    participant SSO as Sso
    participant IdP as Customer IdP
    participant DB

    Web->>Id: POST /connect/token (grant_type=sso, code=...)
    Note over Id: SsoExtensionGrantValidator validates the SsoTokenable

    Web->>Id: GET /sso/login?orgId=…
    Id->>SSO: AddOpenIdConnect("sso") redirect
    SSO->>DB: load SsoConfig for org
    SSO->>IdP: SAML AuthnRequest / OIDC redirect
    IdP-->>SSO: SAML Response / id_token
    SSO->>SSO: map claims, ensure organization-user record
    SSO->>Id: redirect with SsoTokenable
    Id-->>Web: access_token + refresh_token

Integration points

• Identity host — Sso is configured as the external OIDC authority used by Identity's sso handler. The two services trust each other via the oidc-identity client / secret pair.
• Org SSO config — SsoConfig rows in the database, edited via the Web Vault Admin Console UI which calls Api. SSO certificates and metadata are encrypted with data-protection.
• OrganizationUser — on first sign-in, Sso confirms the corresponding OrganizationUser membership (claim mapping done in AccountController).

Self-host

Self-hosted enterprise customers who hold a commercial license can run Sso. The bundled bitwarden.sh stack starts it as one of the optional containers (bitwarden.yml includes it when SSO is enabled).

Entry points for modification

• Adding support for a new identity provider (or a new SAML profile) → extend the SAML / OIDC option builders in Utilities/ and update the org SSO settings page in src/Api/AdminConsole/Controllers/SsoConfigsController.cs.
• Changing claim mapping → edit AccountController and the Models/SsoCallback.cs viewmodel.
• Tightening callback validation → look at SsoExtensionGrantValidator in src/Core/Auth/IdentityServer/RequestValidators/.

For the broader feature view see features/sso-saml.