# Custom SAML for the Nylas Dashboard

Source: https://developer.nylas.com/docs/dev-guide/dashboard-saml-sso/connect-idp/

> **Info:** 
> **This is for Dashboard organization login.** If you want to let your app's end users authenticate with an external IdP, see [Nylas Connect external IdP](/docs/v3/auth/nylas-connect/use-external-idp/) instead.


> **Info:** 
> **Where to find SAML settings:** In the [Nylas Dashboard](https://dashboard-v3.nylas.com), click your organization name in the top-left, then go to **Settings** in the sidebar. Select the **SAML SSO** tab (direct link: [dashboard-v3.nylas.com/organization/settings/identity](https://dashboard-v3.nylas.com/organization/settings/identity)).
> 
> You must have **Admin** or **Owner** access to see this tab.


This guide covers the second step of the SAML SSO wizard: exchanging service provider (SP) details with your IdP to establish the SAML trust. You must [verify your company domain](/docs/dev-guide/dashboard-saml-sso/) first before this step unlocks.

For IdP-specific click-throughs, see the [Okta SAML guide](/docs/dev-guide/dashboard-saml-sso/okta/) or the [Google Workspace SAML guide](/docs/dev-guide/dashboard-saml-sso/google-workspace/).

## Service provider values


To find these values, go to **Settings > SAML SSO** in the [Nylas Dashboard](https://dashboard-v3.nylas.com/organization/settings/identity), then expand the **Connect your identity provider** step. The SP values appear under **Service provider details for your IdP**.

| Nylas SP value | Where to paste it in your IdP |
|---|---|
| **Metadata URL** | Import metadata URL (if your IdP supports it; this imports SP Entity ID and ACS URL automatically) |
| **SP Entity ID** | Audience URI, Audience Restriction, or Identifier (Entity ID) |
| **ACS URL** | Single sign-on URL, Reply URL, or Assertion Consumer Service URL |

> **Info:** 
> **Use the metadata URL when your IdP supports it.** It imports both the Entity ID and ACS URL in one step, and Nylas keeps it current if values change.


## Required SAML attributes

Your IdP must send the following attributes in the SAML assertion:

| Attribute | Required | Notes |
|---|---|---|
| **NameID** (email format) | Yes | The user's work email address. This is how Nylas identifies the user. |
| **groups** | Only for role mapping | A multi-value attribute listing the user's IdP group names. Required if you configure group-to-role mapping in step 3. Nylas only updates roles on login when mappings exist and the assertion includes at least one group value. |

Other attributes in the assertion are ignored.

## Custom SAML

1. Open **Organization settings > SAML SSO** in the [Nylas Dashboard](https://dashboard-v3.nylas.com).
2. Expand the **Connect your identity provider** step.
3. Under **Service provider details for your IdP**, copy the **Metadata URL**, **SP Entity ID**, and **ACS URL** (use the **Copy** button next to each value).
4. In your IdP, create a new SAML 2.0 application (the exact path varies by IdP). Paste the SP values from step 3. If your IdP supports importing from a metadata URL, paste the **Metadata URL** to fill both SP Entity ID and ACS URL automatically.
5. Configure the NameID to send the user's **email address** in `EmailAddress` format.
6. If you plan to use group-to-role mapping, add a `groups` attribute that sends the user's group memberships.
7. Complete the IdP app setup and download or copy your IdP's **metadata XML** (or metadata URL).
8. Back in the Nylas Dashboard, scroll to **Identity provider metadata**. Paste the IdP metadata XML into the **IdP Metadata XML** field, or click **Upload XML file** to load it from disk. Click **Save configuration**.

After saving, the **Connected IdP** card shows the extracted **SSO URL** and **Entity ID** to confirm the metadata was parsed correctly.

## Test SAML login

After saving the IdP configuration:

1. Open a private or incognito browser window.
2. Go to the Nylas Dashboard login page.
3. Enter an email address on your verified domain and click **Continue**.
4. You should be redirected to your IdP's login page.
5. Sign in with the IdP account.
6. On success, you land back in the Nylas Dashboard.

If login fails, see [Troubleshooting](/docs/dev-guide/dashboard-saml-sso/troubleshooting/).

## What's next

- [Manage user access](/docs/dev-guide/dashboard-saml-sso/): Configure JIT provisioning, default role, and group-to-role mapping in step 3 of the wizard.
- [Require SAML sign-in](/docs/dev-guide/dashboard-saml-sso/): Enforce SSO for all users on verified domains once you confirm login works.