> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dovetail.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO

Dovetail supports SAML 2.0 SSO with any compatible identity provider. Admins on Enterprise and Business plans can require users to authenticate via SAML or OpenID Connect.

This guide covers how to set up a SAML SSO connection, including generating connection values in Dovetail, configuring your identity provider, and testing attribute mappings before going live.

<Tip>
  **Before you start:** Allow pop-ups for your Dovetail subdomain (for example, `your-workspace.dovetail.com`). The SAML setup flow opens in a new tab, and pop-up blockers will prevent it from launching.

  **Required attributes:** SAML sign-in requires two user attributes: `email` and `name`. Both must be present and correctly mapped.
</Tip>

***

## Set up SAML with Microsoft Entra ID

This setup requires Admin access in both Dovetail and Entra. You'll switch between both tabs throughout, so keep them open until you're done.

### Step 1: Start the connection in Dovetail

1. In Dovetail, go to **Settings > Authentication**.
2. Under **Authentication connections**, select **Create Enterprise SSO connection**.
3. Choose **Custom SAML** and select **Continue**.
4. Optionally update the connection's display **Label** and the **Button message** shown to users on the sign-in screen, then select **Continue**.
5. A new tab will open with the SAML setup wizard. Select **Get started**, choose **Custom SAML**, and select **Next**.
6. Copy the **Single sign-on URL** and **Service provider entity ID** shown on screen. You'll need these in the next step. Keep this tab open.

***

### Step 2: Create the application in Microsoft Entra ID

1. In the Microsoft Entra admin center, go to **Enterprise applications** and select **New application**.
2. Select **Create your own application**.
3. Enter a name (for example, `Dovetail SAML`), choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**.
   > **Note:** There is a Dovetail app in the Entra gallery, but it uses OIDC. To use SAML, create your own application as described above.
4. Once the application is created, go to **Single sign-on** and select **SAML**.
5. In the **Basic SAML Configuration** section, select **Edit**.
6. Select **Add reply URL** and paste the **Single sign-on URL** you copied from Dovetail.
7. Select **Add identifier** and paste the **Service provider entity ID** you copied from Dovetail.
8. Select **Save**, then close the Basic SAML Configuration panel.
9. In the **SAML Certificates** section, copy the **App Federation Metadata URL**.

***

### Step 3: Finish setup in Dovetail

1. Return to the Dovetail SAML setup tab.
2. Paste the **App Federation Metadata URL** into the **Metadata URL** field.
3. Select **Create connection**, then select **Proceed**.
4. Dovetail will display the required attributes (`email` and `name`). Select **Next** to continue to the connection test.

<Tip>
  **Important:** Creating the connection enables SSO access for any user assigned to the application in Entra. If you haven't yet assigned users or groups in Entra, the connection won't be usable until you do.
</Tip>

***

### Step 4: Test and enable the connection

1. Select **Test connection**. A new window will open prompting you to sign in via Entra.
2. Once sign-in completes, return to the SAML setup tab. You'll see **Testing complete** along with the attribute values returned by Entra.
3. Confirm that both **email** and **name** are mapped to the expected values. If something looks off—for example, **name** mapping to an email address or user principal name—update the attribute mappings in Entra under **Single sign-on > Attributes & Claims** and re-test. See [Troubleshooting attribute mappings](#troubleshooting-attribute-mappings-in-entra) below.
4. Once the test results look correct, select **Enable connection**, then **Proceed**. SAML SSO is now live.

You can close the SAML setup tab. The connection will appear in **Settings > Authentication** under your authentication connections, where you can edit it or toggle it on or off.

<Tip>
  **Important:** Toggling a SAML connection off in Dovetail deletes it. To re-enable SSO, you'll need to recreate the connection. If SAML will be your only login method, keep at least one backup method enabled—such as Google or password—so you're not locked out if the connection ever needs to be reconfigured.
</Tip>

***

## Troubleshooting attribute mappings in Entra

By default, Entra maps the **name** attribute to `user.userprincipalname`, which is often the user's email address rather than their display name. If the connection test shows **name** mapping to an unexpected value, update the mapping:

1. In your Entra application, go to **Single Sign-On> Attributes & Claims** and select **Edit**.
2. Delete the existing **name** claim and add a new claim called `name`.
3. Map the new claim to `user.displayname`, or use a transformation (such as **Join** with `user.givenname` and `user.surname`) if your users don't have a display name set.
4. Save your changes and re-run **Test connection** in Dovetail.

For more on customizing SAML claims in Entra, see [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/saml-claims-customization).

***

## Important: SSO setup and management responsibilities

SSO configuration, validation, and maintenance are managed by your organization, typically by your IT team. While Dovetail provides documentation and in-product guidance, we’re not able to configure or troubleshoot SSO on your behalf.

A workspace Admin is required to set up and manage SSO in Dovetail. We recommend inviting your IT administrator to your workspace and granting them Admin access.

Dovetail’s SSO experience is powered by Auth0 and includes step-by-step setup instructions tailored to your identity provider.