Configure Login with SSO (SAML 2.0)

Category: Login with SSO
On this page:

    This article will guide you through the steps required to configure Login with SSO for SAML 2.0 authentication.

    Note

    Configuration will vary provider-to-provider. Refer to the following Provider Samples as you configure Login with SSO:

    Or, refer to the Field Mappings Reference on this page.

    Step 1: Enabling Login with SSO

    Complete the following steps to enable Login with SSO for SAML 2.0 authentication:

    1. In the Web Vault, navigate to your Organization and open the Settings tab.
    2. In the Identifier field, enter a unique identifier for your Organization.

      Don’t forget to Save your identifier. Users will be required to enter this Identifier upon login.

    3. Navigate to the Business Portal.

      Business Portal button
      Business Portal button
    4. Select the Single Sign-On button.
    5. Check the Enabled checkbox.
    6. From the Type dropdown menu, select the SAML 2.0 option.

    After selecting SAML 2.0, this page will display two sections of fields you will need to configure:

    • SAML Service Provider Configuration
    • SAML Identity Provider Configuration

    Step 2: Service Provider Configuration

    Fields in this section will be required when you Configure your IdP.

    SAML Service Provider Configuration section
    SAML Service Provider Configuration section

    SP Entity ID

    Your Bitwarden endpoint for Login with SSO. This value will be automatically generated based on your Bitwarden instance URL. For all Cloud-hosted instances, https://sso.bitwarden.com/saml2/. For self-hosted instances, domain is based on your configured Server URL.

    Assertion Consumer Service (ACS) URL

    Location where the SAML assertion is sent from the IdP. This value is automatically generated by appending an Organization-identifying string and /Acs to your SP Entity ID. For example, https://sso.bitwarden.com/saml2/abcd123-ef45-gh67-ij89/Acs/.

    For self-hosted instances, domain is based on your configured Server URL.

    Name ID Format

    Format of the SAML assertion. Options include:

    • Unspecified (default)
    • Email Address
    • X.509 Subject Name
    • Windows Domain Qualified Name
    • Kerberos Principal Name
    • Entity Identifier
    • Persistent
    • Transient

    Outbound Signing Algorithm

    Encryption method used by the SAML assertion. Options include:

    Signing Behavior

    Whether Bitwarden will sign SAML assertions. Options include:

    • If IdP Wants Authn Requests Signed (default)
    • Always
    • Never

    Want Assertions Signed

    Check this checkbox if Bitwarden should expect responses from the IdP to be signed.

    Validate Certificates

    Check this checkbox when using trusted and valid certificates from your IdP through a trusted CA. Self-signed certificates may fail unless proper trust chains are configured within the Bitwarden Login with SSO docker image.

    Step 3: Configure Your IdP

    Before you can continue, you must configure your IdP to receive requests from and send responses to Bitwarden using values from Step 2: Service Provider Configuration.

    Depending on your IdP, you may need to create an additional API key or Application ID. We recommend maintaining a distinct Application ID or Reference for Bitwarden.

    Once completed, return to the Bitwarden Business Portal and use the configured values from this step to complete Step 4: Identity Provider Configuration.

    Step 4: Identity Provider Configuration

    Fields in this section should come from the configured values in Step 3: Configure your IdP.

    Required fields will be marked. Failing to provide a value for a required field will cause your configuration to be rejected.

    Entity ID (Required)

    Address or URL of your Identity Server or the IDP Entity ID.

    Binding Type

    Method used by the IdP to respond to Bitwarden SAML assertions. Options include:

    • Redirect (recommended)
    • HTTP POST
    • Artifact

    Single Sign On Service URL (Required if Entity ID is not a URL)

    SSO URL issued by your IdP.

    Single Log Out Service URL

    SLO URL issued by your IdP.

    Note

    Login with SSO currently does not support SLO. This option is planned for future use, however we strongly recommend pre-configuring this field.

    Artifact Resolution Service URL (Required if Binding Type is Artifact)

    URL used for the Artifact Resolution Protocol.

    X509 Public CERTIFICATE (Required unless Signing Behavior is Never)

    The X.509 Base-64 encoded certificate body. Do not include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines or portions of the CER/PEM formatted certificate.

    Warning

    Extra spaces, carriage returns, and other extraneous characters inside this field will cause certificate validation failure. Copy only the certificate data into this field.

    Outbound Signing Algorithm

    Encryption method used by the SAML assertion. Options include:

    Allow Unsolicited Authentication response

    Note

    Login with SSO currently does not support unsolicited (IdP-Initiated) SSO assertions. This checkbox is planned for future use.

    Disable Outbound Logout requests

    Note

    Login with SSO currently does not support SLO. This option is planned for future use, however we strongly recommend pre-configuring this field.

    Want Authentication Requests Signed

    Check this checkbox if your IdP should expect SAML requests from Bitwarden to be signed.

    Field Mappings Reference

    Use the following tables to identify how certain fields in Bitwarden correspond to fields within your Identity Provider’s GUI:

    For Service Provider Configuration

    Bitwarden Azure GSuite JumpCloud Okta OneLogin
    SP Entity ID Identifier (Entity ID) Entity ID SP Entity ID Audience Restriction Audience (Entity ID)
    ACS URL Reply URL (ACS URL) ACS URL ACS URL Single Sign On URL, Recipient URL, Destination URL ACS (Consumer) URL
    Name ID Format Name ID Name ID format SAMLSubject NameID Format Name ID Format SAML nameID format

    For Identity Provider Configuration

    Bitwarden Azure GSuite JumpCloud Okta OneLogin
    Entity ID Azure AD Identifier Google IDP Entity ID IdP Entity ID IdP Issuer URI Issuer URL
    SSO Service URL Login URL Google IDP SSO URL IDP URL Single Sign On URL SAML 2.0 Endpoint (HTTP)
    SLO Service URL Logout URL GSuite does not support SLO SLO Service URL Single Logout URL SLO Endpoint (HTTP)

    Was this helpful?

    Rate this article:

    Email Us

    Want to talk to a human?

    Send Us An Email