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

# Google Workspace SSO

> Configure Google Workspace as a SAML identity provider so your team can sign in to Modus with their Google accounts.

Set up a custom SAML app in Google Workspace to let your team sign in to Modus
using their Google identities. This guide walks through the **Google (identity
provider) side** of the configuration.

## Prerequisites

Before you begin, make sure you have:

* A **Google Workspace admin** account with the privilege to manage apps. A
  super admin works, or a custom admin role that includes the **SSO / apps**
  privilege.
* The **service provider details** from the app you're connecting (its **ACS
  URL**, **Entity ID**, and the **attribute names** it expects). These are
  app-specific — for Modus, you'll find them on your SSO settings page.

## Google Workspace Setup

<Steps>
  <Step title="Open the custom SAML app setup">
    1. Go to the [Google Admin console](https://admin.google.com).
    2. Navigate to **Apps → Web and mobile apps**.
    3. Click **Add app → Add custom SAML app**.
  </Step>

  <Step title="Enter the app details">
    Give the app a name (for example, `Modus`) and optionally upload an icon.
    Click **Continue**.
  </Step>

  <Step title="Grab Google's IdP details">
    This screen shows what Google (the identity provider) supplies to your app:

    | Field           | Description                   |
    | --------------- | ----------------------------- |
    | **SSO URL**     | The sign-in page Google hosts |
    | **Entity ID**   | Google's issuer identifier    |
    | **Certificate** | The signing certificate       |

    The simplest option is **Download Metadata** — that single XML file bundles
    the SSO URL, Entity ID, and certificate together. If your app accepts a
    metadata file or URL, use that and skip copying the three values by hand.

    Click **Continue**.

    <Tip>
      Uploading the metadata file avoids transcription errors with the
      certificate and Entity ID, which are the most common source of failed
      SSO setups.
    </Tip>
  </Step>

  <Step title="Enter the service provider details">
    Now enter the values the **app** provided:

    | Field               | What to enter                                                      |
    | ------------------- | ------------------------------------------------------------------ |
    | **ACS URL**         | Where Google posts the SAML assertion (the app's "reply URL")      |
    | **Entity ID**       | The app's identifier / Audience URI                                |
    | **Start URL**       | Optional — only needed for IdP-initiated login                     |
    | **Signed response** | Leave the default unless the app requires the full response signed |
    | **Name ID format**  | Typically **EMAIL**                                                |
    | **Name ID**         | **Basic Information > Primary email**                              |

    Click **Continue**.

    <Warning>
      The **Entity ID** and **ACS URL** must match the app's expected values
      *exactly* — trailing slashes matter. A mismatch is the most common reason
      logins fail.
    </Warning>
  </Step>

  <Step title="Map attributes">
    Map Google directory fields to the attribute names the app expects. The
    app's docs list the exact names. Common mappings:

    | Google directory field | App attribute name            |
    | ---------------------- | ----------------------------- |
    | Primary email          | `email`                       |
    | First name             | `firstName` (or `given_name`) |
    | Last name              | `lastName` (or `family_name`) |

    If the app uses **group-based** roles, add a **Group membership** mapping as
    well and select which groups to send.

    Click **Finish**.
  </Step>

  <Step title="Turn the app ON">
    This is the step people most often miss.

    1. On the app's page, click **User access**.
    2. Set the service status to **ON for everyone** (or ON for specific
       organizational units / groups).
    3. Click **Save**.
  </Step>

  <Step title="Wait and test">
    Changes can take a few minutes — and occasionally up to \~24 hours — to
    propagate, though it's usually fast.

    1. Test **IdP-initiated** login first if available, from the user's Google
       app launcher.
    2. Then test **SP-initiated** login by signing in from the app itself.
  </Step>
</Steps>

## Common gotchas

* **Entity ID and ACS URL must match exactly.** Trailing slashes and `http` vs.
  `https` matter — copy them character-for-character from the app.
* **Name ID format mismatch.** If the Name ID format doesn't match what the app
  keys users on, logins will succeed at Google but the app may reject the user
  or create a duplicate account.

<Note>
  The ACS URL, Entity ID, and attribute names are app-specific. For Modus, copy
  these values from your SSO settings page and plug them into the **Service
  provider details** and **Attribute mapping** steps above. Reach out to
  [support@getmodus.com](mailto:support@getmodus.com) if you need them.
</Note>