vaultwarden/SSO.md

SSO using OpenId Connect

To use an external source of authentication your SSO will need to support OpenID Connect :

• And OpenID Connect Discovery endpoint should be available
• Client authentication will be done using Id and Secret.

A master password will still required and not controlled by the SSO (depending of your point of view this might be a feature ;). This introduce another way to control who can use the vault without having to use invitation or using an LDAP.

Configuration

The following configurations are available

• SSO_ENABLED : Activate the SSO
• SSO_ONLY : disable email+Master password authentication
• SSO_SIGNUPS_MATCH_EMAIL: On SSO Signup if a user with a matching email already exists make the association (default true)
• SSO_AUTHORITY : the OpendID Connect Discovery endpoint of your SSO
  • Should not include the /.well-known/openid-configuration part and no trailing /
  • $SSO_AUTHORITY/.well-known/openid-configuration should return the a json document: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse
• SSO_SCOPES : Optional, allow to override scopes if needed (default "email profile")
• SSO_AUTHORIZE_EXTRA_PARAMS : Optional, allow to add extra parameter to the authorize redirection (default "")
• SSO_PKCE: Activate PKCE for the Auth Code flow. Recommended but disabled for now waiting for feedback on support (default false).
• SSO_AUDIENCE_TRUSTED: Optional, Regex to trust additionnal audience for the IdToken (client_id is always trusted). Use single quote when writing the regex: '^$'.
• SSO_CLIENT_ID : Client Id
• SSO_CLIENT_SECRET : Client Secret
• SSO_MASTER_PASSWORD_POLICY: Optional Master password policy
• SSO_AUTH_ONLY_NOT_SESSION: Enable to use SSO only for authentication not session lifecycle
• SSO_CLIENT_CACHE_EXPIRATION: Cache calls to the discovery endpoint, duration in seconds, 0 to disable (default 0);
• SSO_DEBUG_TOKENS: Log all tokens (default false, LOG_LEVEL=debug is required)

The callback url is : https://your.domain/identity/connect/oidc-signin

Account and Email handling

When logging with SSO an identifier ({iss}/{sub} claims from the IdToken) is saved in a separate table (sso_users). This is used to link to the SSO provider identifier without changing the default Vaultwarden user uuid. This is needed because:

• Storing the SSO identifier is important to prevent account takeover due to email change.
• We can't use the identifier as the User uuid since it's way longer (Max 255 chars for the sub part, cf spec).
• We want to be able to associate existing account based on email but only when the user log for the first time (controlled by SSO_SIGNUPS_MATCH_EMAIL).
• We need to be able to associate with existing stub account, such as the one created when inviting a user to an org (association is possible only if the user does not have a private key).

Additionnaly:

• Signup to Vaultwarden will be blocked if the Provider report the email as unverified.
• Changing the email need to be done by the user since it require updating the key. On login if the email returned by the provider is not the one saved in Vaultwarden an email will be sent to the user to ask him to update it.
• If set SIGNUPS_DOMAINS_WHITELIST is applied on SSO signup and when attempting to change the email.

This mean that if you ever need to change the provider url or the provider itself; you'll have to first delete the association then ensure that SSO_SIGNUPS_MATCH_EMAIL is activated to allow a new association.

To delete the association (this has no impact on the Vaultwarden user):

TRUNCATE TABLE sso_users;

Client Cache

By default the client cache is disabled since it can cause issues with the signing keys.
This mean that the discovery endpoint will be called again each time we need to interact with the provider (generating authorize_url, exhange the authorize code, refresh tokens). This is suboptimal so the SSO_CLIENT_CACHE_EXPIRATION allow you to configure an expiration that should work for your provider.

As a protection against a misconfigured expiration if the validation of the IdToken fails then the client cache is invalidated (but you'll periodically have an unlucky user ^^).

Google example (Rolling keys)

If we take Google as an example checking the discovery endpoint response headers we can see that the max-age of the cache control is set to 3600 seconds. And the jwk_uri response headers usually contain a max-age with an even bigger value. / Combined with user feedback we can conclude that Google will roll the signing keys each week.

Setting the cache expiration too high has diminishing return but using something like 600 (10 min) should provide plenty benefits.

Rolling keys manually

If you want to roll the used key, first add a new one but do not immediately start signing with it. Wait for the delay you configured in SSO_CLIENT_CACHE_EXPIRATION then you can start signing with it.

As mentionned in the Google example setting too high of a value has dimishing return even if you do not plan to roll the keys.

Keycloak

Default access token lifetime might be only 5min, set a longer value otherwise it will collide with VaultWarden front-end expiration detection which is also set at 5min.
At the realm level

• Realm settings / Tokens / Access Token Lifespan to at least 10min (accessTokenLifespan setting when using kcadm.sh).
• Realm settings / Sessions / SSO Session Idle/Max for the Refresh token lifetime

Or for a specific client in Clients / Client details / Advanced / Advanced settings you can find Access Token Lifespan and Client Session Idle/Max.

Server configuration, nothing specific just set:

• SSO_AUTHORITY=https://${domain}/realms/${realm_name}
• SSO_CLIENT_ID
• SSO_CLIENT_SECRET
• SSO_PKCE=true

Testing

If you want to run a testing instance of Keycloak a docker-compose is available.

Authelia

To obtain a refresh_token to be able to extend session you'll need to add the offline_access scope.

Config will look like:

• SSO_SCOPES="email profile offline_access"

Authentik

Default access token lifetime might be only 5min, set a longer value otherwise it will collide with VaultWarden front-end expiration detection which is also set at 5min.
To change the tokens expiration go to Applications / Providers / Edit / Advanced protocol settings.

Starting with 2024.2 version you will need to add the offline_access scope and ensure it's selected in Applications / Providers / Edit / Advanced protocol settings / Scopes (Doc).

Server configuration should look like:

• SSO_AUTHORITY=https://${domain}/application/o/${application_name}/ : trailing / is important
• SSO_SCOPES="email profile offline_access"
• SSO_CLIENT_ID
• SSO_CLIENT_SECRET
• SSO_PKCE=true

GitLab

Create an application in your Gitlab Settings with

• redirectURI: https://your.domain/identity/connect/oidc-signin
• Confidential: true
• scopes: openid, profile, email

Then configure your server with

• SSO_AUTHORITY=https://gitlab.com
• SSO_CLIENT_ID
• SSO_CLIENT_SECRET
• SSO_PKCE=true

Google Auth

Google Documentation.
By default without extra configuration you won´t have a refresh_token and session will be limited to 1h.

Configure your server with :

• SSO_AUTHORITY=https://accounts.google.com

•   SSO_AUTHORIZE_EXTRA_PARAMS="
    access_type=offline
    prompt=consent
    "
  

• SSO_PKCE=true
• SSO_CLIENT_ID
• SSO_CLIENT_SECRET

Kanidm

Kanidm recommend always running with PKCE:

Config will look like:

• SSO_PKCE=true

Otherwise you can disable the PKCE requirement with: kanidm system oauth2 warning-insecure-client-disable-pkce CLIENT_NAME --name admin.

Microsoft Entra ID

1. Create an "App registration" in Entra ID following Identity | Applications | App registrations.
2. From the "Overview" of your "App registration", you'll need the "Directory (tenant) ID" for the SSO_AUTHORITY variable and the "Application (client) ID" as the SSO_CLIENT_ID value.
3. In "Certificates & Secrets" create an "App secret" , you'll need the "Secret Value" for the SSO_CLIENT_SECRET variable.
4. In "Authentication" add https://vaultwarden.example.org/identity/connect/oidc-signin as "Web Redirect URI".
5. In "API Permissions" make sure you have profile, email and offline_access listed under "API / Permission name" (offline_access is required, otherwise no refresh_token is returned, see https://github.com/MicrosoftDocs/azure-docs/issues/17134).

Only the v2 endpooint is compliant with the OpenID spec, see https://github.com/MicrosoftDocs/azure-docs/issues/38427 and https://github.com/ramosbugs/openidconnect-rs/issues/122.

Your configuration should look like this:

• SSO_AUTHORITY=https://login.microsoftonline.com/${Directory (tenant) ID}/v2.0
• SSO_SCOPES="email profile offline_access"
• SSO_CLIENT_ID=${Application (client) ID}
• SSO_CLIENT_SECRET=${Secret Value}

Zitadel

To obtain a refresh_token to be able to extend session you'll need to add the offline_access scope.

Additionnaly Zitadel include the Project id and the Client Id in the audience of the Id Token. For the validation to work you will need to add the Resource Id as a trusted audience (Client Id is trusted by default). You can control the trusted audience with the config SSO_AUDIENCE_TRUSTED

It appears it's not possible to use PKCE with confidential client so it needs to be disabled.

Config will look like:

- `SSO_AUTHORITY=https://${provider_host}`
- `SSO_SCOPES="email profile offline_access"`
- `SSO_CLIENT_ID`
- `SSO_CLIENT_SECRET`

• SSO_AUDIENCE_TRUSTED='^${Project Id}$'
• SSO_PKCE=false

Session lifetime

Session lifetime is dependant on refresh token and access token returned after calling your SSO token endpoint (grant type authorization_code). If no refresh token is returned then the session will be limited to the access token lifetime.

Tokens are not persisted in VaultWarden but wrapped in JWT tokens and returned to the application (The refresh_token and access_token values returned by VW identity/connect/token endpoint). Note that VaultWarden will always return a refresh_token for compatibility reasons with the web front and it presence does not indicate that a refresh token was returned by your SSO (But you can decode its value with https://jwt.io and then check if the token field contain anything).

With a refresh token present, activity in the application will trigger a refresh of the access token when it's close to expiration (5min in web client).

Additionnaly for certain action a token check is performed, if we have a refresh token we will perform a refresh otherwise we'll call the user information endpoint to check the access token validity.

Disabling SSO session handling

If you are unable to obtain a refresh_token or for any other reason you can disable SSO session handling and revert to the default handling. You'll need to enable SSO_AUTH_ONLY_NOT_SESSION=true then access token will be valid for 2h and refresh token will allow for an idle time of 7 days (which can be indefinitely extended).

Debug information

Running with LOG_LEVEL=debug you'll be able to see information on token expiration.

Desktop Client

There is some issue to handle redirection from your browser (used for sso login) to the application.

Chrome

Probably not much hope, an issue is open on the subject and it appears that both Linux and Windows are not working.

Firefox

On Windows you'll be presented with a prompt the first time you log to confirm which application should be launched (But there is a bug at the moment you might end-up with an empty vault after login atm).

On Linux it's a bit more tricky. First you'll need to add some config in about:config :

network.protocol-handler.expose.bitwarden=false
network.protocol-handler.external.bitwarden=true

If you have any doubt you can check mailto to see how it's configured.

The redirection will still not work since it appears that the association to an application can only be done on a link/click. You can trigger it with a dummy page such as:

data:text/html,<a href="bitwarden:///dummy">Click me to register Bitwarden</a>

From now on the redirection should now work. If you need to change the application launched you can now find it in Settings by using the search function and entering application.