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

# Google Workspace SSO

> Connect Google Workspace to Summand via the WorkOS Admin Portal — custom SAML 2.0.

Google Workspace integrates with Summand via SAML 2.0 through the WorkOS Admin Portal. (Direct **Continue with Google** OAuth is also available on the login screen for any Google user — that's separate from org-managed SSO.)

## Setup

<Steps>
  <Step title="Verify your domain in Summand">
    **Settings → Organization → Domain Verification → Configure**, then publish the DNS TXT record. Verified domains are routed to your Workspace SSO on sign-in.
  </Step>

  <Step title="Open the SSO Admin Portal">
    **Settings → Organization → Single Sign-On → Configure**. The portal opens scoped to your org.
  </Step>

  <Step title="Pick Google Workspace">
    Choose **Google Workspace** in the portal. WorkOS provides:

    * The **ACS URL**
    * The **Entity ID**
    * The required attributes: `email`, `name`, optionally `given_name`, `family_name`
  </Step>

  <Step title="Create the SAML app in Google Admin">
    From [admin.google.com](https://admin.google.com), go to **Apps → Web and mobile apps → Add app → Add custom SAML app**. Paste the ACS URL and Entity ID from the portal; set Name ID format to **EMAIL** and Name ID to **Basic Information → Primary email**.

    Detailed Google-side steps are in the [WorkOS Google Workspace guide](https://workos.com/docs/sso/identity-provider-handbook/google-workspace).
  </Step>

  <Step title="Configure attribute mapping in Google">
    Map these attributes:

    | App attribute | Source                   |
    | ------------- | ------------------------ |
    | `email`       | Primary email            |
    | `name`        | Full name (first + last) |
    | `given_name`  | First name               |
    | `family_name` | Last name                |
  </Step>

  <Step title="Download Google's metadata">
    On the SAML app's IdP details page, download the **Metadata** XML or copy the SSO URL, Entity ID, and certificate.
  </Step>

  <Step title="Return to the WorkOS portal">
    Upload the metadata XML (or paste the individual fields). WorkOS validates and pre-fills.
  </Step>

  <Step title="Enable the SAML app for users">
    Back in Google Admin, on the SAML app page, set the service status to **On for everyone** (or for a specific OU). New apps default to *Off*, which is the most common cause of "user gets blocked at Google" errors.
  </Step>

  <Step title="Test the connection">
    Click *Test connection* in the WorkOS portal. WorkOS runs an end-to-end Google sign-in flow and reports the result.
  </Step>
</Steps>

## Group → role mapping

Google's custom SAML apps don't send group memberships in the SAML response by default. If you want group-based role mapping in Summand, pick the option that fits:

* **Manual mapping by Google Group address** — list a Google Group's email in the WorkOS portal and bind it to a Summand role.
* **Cloud Identity** — Google Cloud Identity supports richer claim attributes, including arbitrary group sends.
* **Workspace-only orgs** — for most teams, mapping by group address is enough and removes the need to enable Cloud Identity.

## Why no Directory Sync?

Google Workspace **does** support SCIM, and WorkOS supports a Workspace SCIM connector. If you want it, **Settings → Organization → Directory Sync → Configure** and pick **Google Workspace** in the portal — note that this requires your Workspace admin to set up a service account and enable the Admin SDK API on the Google side. The WorkOS portal walks through that.

## Removing the connection

**Single Sign-On → Disable** in the WorkOS portal. Existing sessions persist until expiry; revoke explicitly via **Settings → Organization → Members** if you need an immediate sign-out.