help/_articles/login-with-sso/configure-sso-saml.md

---
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:
- <http://www.w3.org/2001/04/xmldsig-more#rsa-sha256> (*default*)
- <http://www.w3.org/2000/09/xmldsig#rsa-sha1>
- <http://www.w3.org/2000/09/xmldsig#rsa-sha384>
- <http://www.w3.org/2000/09/xmldsig#rsa-sha512>

#### 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:
- <http://www.w3.org/2001/04/xmldsig-more#rsa-sha256> (*default*)
- <http://www.w3.org/2000/09/xmldsig#rsa-sha1>
- <http://www.w3.org/2000/09/xmldsig#rsa-sha384>
- <http://www.w3.org/2000/09/xmldsig#rsa-sha512>

#### 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)<br>urn:oid:0.9.2342.19200300.100.1.1<br>Sub<br>UID<br>UPN<br>EPPN|
|Email|Email<br>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress<br>urn:oid:0.9.2342.19200300.100.1.3<br>Mail<br>EmailAddress|Preferred_Username<br>Urn:oid:0.9.2342.19200300.100.1.1<br>UID|
|Name|Name<br>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name<br>urn:oid:2.16.840.1.113730.3.1.241<br>urn:oid:2.5.4.3<br>DisplayName<br>CN|First Name + “ “ + Last Name (see below)|
|First Name|urn:oid:2.5.4.42<br>GivenName<br>FirstName<br>FN<br>FName<br>Nickname|
|Last Name|urn:oid:2.5.4.4<br>SN<br>Surname<br>LastName|