--- layout: article title: Configure Login with SSO (SAML 2.0) categories: [login-with-sso] featured: false popular: false tags: [sso, saml, saml2.0, idp, identity] order: 03 --- This article will guide you through the steps required to configure Login with SSO for SAML 2.0 authentication. {% callout info %} **Configuration will vary provider-to-provider.** Refer to the following Provider Samples as you configure Login with SSO: - [ADFS Sample]({% link _articles/login-with-sso/saml-adfs.md%}) - [Auth0 Sample]({% link _articles/login-with-sso/saml-auth0.md %}) - [AWS Sample]({% link _articles/login-with-sso/saml-aws.md %}) - [Azure Sample]({% link _articles/login-with-sso/saml-azure.md %}) - [Duo Sample]({% link _articles/login-with-sso/saml-duo.md %}) - [Google Sample]({% link _articles/login-with-sso/saml-google.md %}) - [JumpCloud Sample]({% link _articles/login-with-sso/saml-jumpcloud.md %}) - [Keycloak Sample]({% link _articles/login-with-sso/saml-keycloak.md %}) - [Okta Sample]({% link _articles/login-with-sso/saml-okta.md %}) - [OneLogin Sample]({% link _articles/login-with-sso/saml-onelogin.md %}) - [PingFederate Sample]({% link _articles/login-with-sso/saml-pingfederate.md %}) Or, refer to the [Field Mappings Reference](#field-mappings-reference) on this page. {% endcallout %} ## 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: {% image /sso/org-id.png Enter an Identifier %} Don't forget to **Save** your identifier. Users will be required to enter this **Identifier** upon login. 3. Navigate to the **Business Portal**. {% image /organizations/business-portal-button-overlay.png Business Portal button %} 4. Select the **Single Sign-On** button. 4. Check the **Enabled** checkbox. 5. 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](#step-3-configure-your-idp). {% image /sso/sso-saml-sp.png 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: - (*default*) - - - #### 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](#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. {% comment %} PLACEHOLDER TO ADD PROVIDER SCREENSHOTS Refer to the following samples for assistance: - [{% icon fa-download %} ADFS Sample]({{site.baseurl}}/files/bitwarden_export.csv) - [{% icon fa-download %} Azure Sample]({{site.baseurl}}/files/bitwarden_export.csv) - [{% icon fa-download %} GSuite Sample]({{site.baseurl}}/files/bitwarden_export.csv) - [{% icon fa-download %} JumpCloud Sample]({{site.baseurl}}/files/bitwarden_export.csv) - [{% icon fa-download %} Okta Sample]({{site.baseurl}}/files/bitwarden_export.csv) - [{% icon fa-download %} OneLogin Sample]({{site.baseurl}}/files/bitwarden_export.csv) {% endcomment %} 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). ## Step 4: Identity Provider Configuration Fields in this section should come from the configured values in [Step 3: Configure your IdP](#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. {% image /sso/sso-saml-ip.png %} #### 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. {% callout info %} Login with SSO currently **does not** support SLO. This option is planned for future use, however we strongly recommend pre-configuring this field. {% endcallout %} #### 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. {% callout 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. {% endcallout %} #### Outbound Signing Algorithm Encryption method used by the SAML assertion. Options include: - (*default*) - - - #### Allow Unsolicited Authentication response {% callout info %} Login with SSO currently **does not** support unsolicited (IdP-Initiated) SSO assertions. This checkbox is planned for future use. {% endcallout %} #### Disable Outbound Logout requests {% callout info %} Login with SSO currently **does not** support SLO. This option is planned for future use, however we strongly recommend pre-configuring this field. {% endcallout %} #### 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)| ## SAML Attributes & Claims An **email address is required for account provisioning**, which can be passed as any of the attributes or claims in the below table. A unique user identifier is also highly recommended. If absent, Email will be used in its place to link the user. Attributes/Claims are listed in order of preference for matching, including Fallbacks where applicable: |Value|Claim/Attribute|Fallback Claim/Attribute| |-----|---------------|------------------------| |Unique ID|NameID (when not Transient)
urn:oid:0.9.2342.19200300.100.1.1
Sub
UID
UPN
EPPN| |Email|Email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
urn:oid:0.9.2342.19200300.100.1.3
Mail
EmailAddress|Preferred_Username
Urn:oid:0.9.2342.19200300.100.1.1
UID| |Name|Name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
urn:oid:2.16.840.1.113730.3.1.241
urn:oid:2.5.4.3
DisplayName
CN|First Name + “ “ + Last Name (see below)| |First Name|urn:oid:2.5.4.42
GivenName
FirstName
FN
FName
Nickname| |Last Name|urn:oid:2.5.4.4
SN
Surname
LastName|