# Google Workspace SSO Setup


{{< announcement >}}
The Single Sign-On (SSO) feature is available in the [Enterprise](https://www.rudderstack.com/enterprise-quote/) plan only.
{{< /announcement >}}

This guide lists the steps to set up your Google Workspace SAML integration with RudderStack.

## Overview

This integration supports the following features:

- SP-initiated SSO
- JIT (Just In Time) Provisioning
- Group-based provisioning (via SAML group membership)

Note that:

- RudderStack supports only the [SAML 2.0 protocol](https://auth0.com/intro-to-iam/what-is-saml) for SSO.
- RudderStack does not support IdP-initiated authentication. Make sure the users log in through [https://app.rudderstack.com/sso](https://app.rudderstack.com/sso).
- As this is a **JIT (Just In Time) provisioning-only** integration, RudderStack does not support SCIM with Google Workspace.
- User deletions and group membership changes are **not propagated** from Google Workspace to RudderStack. When you remove a user or move them between groups in Google Workspace, you must update or remove their access manually in RudderStack.

## Step 1: Create a custom SAML app

1. Sign in to the [Google Admin console](https://admin.google.com/) as an administrator.
2. Go to **Apps** > **Web and mobile apps**.
3. Click **Add app** > **Add custom SAML app**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-1.webp" alt="Add custom SAML app option" >}}

4. Enter the **App name** (for example, `RudderStack`), optionally upload an icon, and click **Continue**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-2.webp" alt="App details" >}}

## Step 2: Share the IdP metadata with RudderStack

1. On the **Google Identity Provider details** page, click **Download Metadata** to download the IdP metadata file. Alternatively, copy the **SSO URL** and **Entity ID** and download the **Certificate**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-3.webp" alt="Google Identity Provider details" >}}

{{< warning >}}
Before sharing the IdP metadata, verify that it declares both HTTP-Redirect and HTTP-POST SAML bindings. 

RudderStack uses AWS Cognito, which sends the initial login request with HTTP-Redirect, so metadata that advertises only HTTP-POST will be rejected.
{{< /warning >}}

2. Share the downloaded metadata file (or the SSO URL, Entity ID, and certificate) with the [RudderStack team](mailto:support@rudderstack.com) to enable SSO for your organization.

{{< info >}}
While sharing the metadata, also let the RudderStack team know:

- Which workspace you would like to set as the **default workspace** for your organization. New users who sign in through SSO for the first time will automatically land in this workspace.
- Whether you want RudderStack to also create a **personal organization** for each new SSO user. This is **off by default**.

You can also opt out of setting up a default workspace altogether if you don't want your SSO users to get automatic access to a shared workspace.
{{< /info >}}

3. Click **Continue**.

## Step 3: Set up the service provider details

On the **Service Provider Details** page, enter the following information:

| Field | Value |
| :-- | :-- |
| ACS URL | `https://auth2.rudderstack.com/saml2/idpresponse` |
| Entity ID | `urn:amazon:cognito:sp:us-east-1_ABZiTjXia` |
| Start URL | `https://app.rudderstack.com/sso?domain=<YOUR_EMAIL_DOMAIN>` <br /><br />Replace `<YOUR_EMAIL_DOMAIN>` with your organization's email domain. For example, if your employee email is `alex@example.com`, then set the **Start URL** to `https://app.rudderstack.com/sso?domain=example.com`. <br /><br />{{< warning >}}Specify only a single email domain for the `<YOUR_EMAIL_DOMAIN>` parameter — no comma-separated list or array of domains is allowed.{{< /warning >}} |
| Name ID format | `EMAIL` |
| Name ID | Go to **Basic Information** > **Primary email** |

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-4.webp" alt="Service provider details" >}}

## Step 4: Configure attribute mapping

On the **Attribute mapping** page, map the following Google Directory attributes to the app attributes that RudderStack expects:

| Google Directory attribute | App attribute |
| :-- | :-- |
| Primary email | `Email` |
| Last name | `LastName` |

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-5.webp" alt="Attribute mapping" >}}

{{< danger >}}
Your SSO authentication will fail if these mandatory attributes are not mapped correctly.
{{< /danger >}}

## Step 5: Turn on the app

1. In the **Web and mobile apps** list, select your newly created RudderStack SAML app.
2. Click **User access**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-6.webp" alt="User access" >}}

3. Turn the **Service status** **ON for everyone** (or for the specific organizational units that should access RudderStack), and click **Save**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-7.webp" alt="Service status" >}}

{{< warning >}}
Make sure the email addresses your users use to sign in to RudderStack match the email addresses they use to sign in to your Google Workspace domain.
{{< /warning >}}

## Step 6: Send group membership in the SAML response

If you want RudderStack to automatically assign users to RudderStack groups based on their Google Workspace group membership, configure your SAML app to send the `memberOf` attribute in the SAML response.

1. On the **Attribute mapping** page, go to the **Group membership (optional)** section.
2. Under **Google Groups**, add the Google Workspace groups whose membership you want to send to RudderStack.
3. Set the corresponding **App attribute** to `memberOf`.
4. Click **Save**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-8.webp" alt="Group membership mapping to the memberOf attribute" >}}

{{< warning >}}
For group-based provisioning to work, your SAML authentication **must** send the `memberOf` attribute. If the SAML response does not include `memberOf`, RudderStack cannot map the user to a group.
{{< /warning >}}

## Step 7: Map identity provider groups in RudderStack

Once your SAML app sends the `memberOf` attribute, create a group mapping in RudderStack to link each Google Workspace group to a RudderStack group.

{{< info >}}
Before creating a mapping, make sure the target RudderStack groups already exist. Refer to the [Manage Group Policies]({{< ref "access-management/groups.md" >}}) guide to create groups.
{{< /info >}}

1. In RudderStack, go to **Settings** > **Access Management** > **Group Mapping**.
2. Click **Add mapping**.
3. In the **Add group mapping** dialog, enter the **IDP group name**. This must match the Google Workspace group's display name exactly as it appears in your identity provider.
4. Select the **RudderStack group** to map it to, and click **Save**.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-9.webp" alt="Add group mapping dialog" >}}

The mapping now appears in the **Group Mapping** list. In the example below, a user in the `qa` Google Workspace group is granted access to the `group2` RudderStack group on sign-in.

{{< image src="images/user-guides/google-sso/rudderstack-google-sso-10.webp" alt="Group mapping list in Access Management" >}}

{{< warning >}}
Group-based access is applied **only at the first sign-in**. If a user is later moved to a different group in Google Workspace, the change is **not** reflected in RudderStack — you must update their permissions manually in the RudderStack app. The same applies to deprovisioning: to revoke a user's access, you must remove it manually in RudderStack.
{{< /warning >}}

## Enable SSO login

Your users can now sign in to RudderStack through `https://app.rudderstack.com/sso?domain=<YOUR_EMAIL_DOMAIN>` (the **Start URL** you configured in [Step 3](#step-3-set-up-the-service-provider-details)).

{{< warning >}}
RudderStack does not support IdP-initiated authentication, so users must always start the login from this URL.
{{< /warning >}}

## Debugging

{{< customreadfile "/includes/sso-debugging.md" >}}

#### Invalid samlResponse or relayState from identity provider

{{< image src="images/user-guides/sso-errors-1.webp" alt="SSO errors" >}}

The above error indicates you tried the [IdP](https://support.okta.com/help/s/article/okta-saml?language=en_US)-initiated authentication flow. As stated above, this integration supports only [Service Provider (SP)-initiated SSO flow](#overview).

RudderStack recommends initiating the SSO authentication by following all the above SSO configuration steps correctly and making sure the users log in through `https://app.rudderstack.com/sso`.

#### Required String parameter 'RelayState' is not present

{{< image src="images/user-guides/sso-errors-2.webp" alt="SSO errors" >}}

The above error indicates that you did not set up your SSO app correctly. Make sure to:

- Set the **Entity ID** field to `urn:amazon:cognito:sp:us-east-1_ABZiTjXia`.
- Set the **Name ID format** to `EMAIL` and the **Name ID** to **Primary email**.
- Configure the other [service provider settings](#step-3-set-up-the-service-provider-details) correctly.

## FAQ

{{< customreadfile "/includes/sso-faq.md" >}}