# Set up SAML SSO with Google Workspace

Source: https://developer.nylas.com/docs/dev-guide/dashboard-saml-sso/google-workspace/

> **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 walks through creating a custom SAML app in Google Workspace Admin Console and connecting it to your Nylas organization. Complete [domain verification and the Custom SAML step](/docs/dev-guide/dashboard-saml-sso/connect-idp/) before following these instructions.

You need Google Workspace Admin access.

## 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.


## Create the Google Workspace SAML app

1. Go to the [Google Workspace Admin Console](https://admin.google.com) and sign in as an admin.
2. Navigate to **Apps > Web and mobile apps**.
3. Click **Add app > Add custom SAML app**.
4. Enter an app name (for example, `Nylas Dashboard`) and click **Continue**.
5. On the **Google Identity Provider details** screen, click **Download metadata** to save the IdP metadata XML file. You will paste this into Nylas later. Click **Continue**.
6. On the **Service provider details** screen, fill in the SP values from your Nylas Dashboard (**Connect your identity provider** step):
   - **ACS URL**: paste the **ACS URL**.
   - **Entity ID**: paste the **SP Entity ID**.
   - Leave **Start URL** empty.
   - Set **Name ID format** to `EMAIL`.
   - Set **Name ID** to **Basic Information > Primary email**.
7. Under **Signed response**, leave this **OFF**. Nylas validates only the Assertion signature, not the outer Response envelope. Turning it on is the most common misconfiguration that causes login failures.
8. Click **Continue**, then **Finish**.

## Assign users to the app

Google Workspace SAML apps are off by default. Users must be assigned before they can sign in.

1. In the Admin Console, open the app you just created.
2. Click **User access**.
3. Turn the service **On** for the relevant organizational unit (OU) or for all users. Alternatively, use **Groups** to assign specific groups.
4. Click **Save**.

## Complete setup in Nylas

1. Back in the Nylas Dashboard (**Connect your identity provider** step), open the **Identity provider metadata** section.
2. Paste the metadata XML file you downloaded in step 5 above into the **IdP Metadata XML** field, or click **Upload XML file**.
3. Click **Save configuration**.

The **Connected IdP** card confirms the saved SSO URL and entity ID.

## Test Google Workspace login

1. Open a private browser window.
2. Go to the Nylas Dashboard login page.
3. Enter an email on your verified domain and click **Continue**.
4. You should be redirected to the Google sign-in page.
5. Sign in with the Google Workspace account and confirm you land in the Dashboard.

> **Info:** 
> **Always use SP-initiated login.** Start from the Nylas login page and enter the email. Do not use the **Test SAML Login** button in Google Admin Console. That button triggers an IdP-initiated flow that Nylas does not support and will result in an error.

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

## Google Workspace gotchas

**"App not assigned" error in Google**: The signed-in Google account is not assigned to the SAML app. Go to Admin Console > the app > User access and assign the user or their OU.

**Email/domain mismatch**: The user's Google Workspace email, the domain claimed in Nylas, and the email entered on the Nylas login page must all match exactly. For example, if you claimed `company.com`, the Google account must be `name@company.com`.

**Certificate rotation**: When Google rotates the IdP signing certificate, existing sessions continue to work but new logins fail with a signature error. To fix it: download fresh metadata XML from the Admin Console and re-paste it in the Nylas Dashboard wizard.

**No built-in SCIM**: Google Workspace does not expose a native SCIM endpoint for custom SAML apps. Automatic user provisioning from Google requires a third-party relay (such as Okta sitting in front of Google) or manual account management. SAML SSO login and JIT provisioning work without SCIM.

## What's next

- [Manage user access](/docs/dev-guide/dashboard-saml-sso/): Configure JIT provisioning and group-to-role mapping.
- [Require SAML sign-in](/docs/dev-guide/dashboard-saml-sso/): Enforce SSO once login is confirmed.
- [Troubleshooting](/docs/dev-guide/dashboard-saml-sso/troubleshooting/): Fix common setup and login errors.