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

# Google Workspace OIDC

> Connect Modem to Google Workspace with an OIDC client

This guide sets up [Enterprise SSO](/docs/enterprise/sso) with Google Workspace using OIDC. Read the overview first if you haven't — it covers domain verification, roles, and the limitations that apply to every provider.

Google's consoles are redesigned regularly, so treat the menu paths and field labels below as a guide; the exact labels move between releases.

## Why OIDC and not SAML

Google Workspace can also act as a SAML identity provider, but Modem recommends OIDC here. Google's OIDC `sub` claim is a stable, globally unique user id — Google's discovery document advertises `subject_types_supported: ["public"]` — so there is no identifier to map and nothing to get wrong. With SAML you would have to choose and configure one yourself.

## Prerequisites

* Enterprise SSO enabled for your Modem organization, and the **owner** role in it
* Access to the Google Cloud project attached to your Workspace, with permission to create OAuth credentials
* Access to DNS for the email domain you are claiming

<Note>
  Unlike Okta and Entra, this integration is created in the **Google Cloud Console**, not in the Google Workspace Admin console. The Admin
  console is only involved if you want to restrict which users can reach the app.
</Note>

## Setup

Unlike the SAML providers, this one is a single pass: Modem's redirect URI is available before you register anything, so there is no placeholder to come back and replace.

<Steps>
  <Step title="Copy Modem's redirect URI">
    In the [Modem dashboard](https://app.modem.dev), go to **Settings** → **SSO**. Copy the **OIDC redirect URI**, which looks like
    `https://app.modem.dev/api/auth/sso/callback/org-<id>`.
  </Step>

  <Step title="Configure the OAuth consent screen">
    In the Google Cloud Console for the project attached to your Workspace, open **APIs & Services** → **OAuth consent screen** and
    set the user type to **Internal**, so only users in your Workspace can use the app.
  </Step>

  <Step title="Create the OAuth client">
    Go to **APIs & Services** → **Credentials** → **Create credentials** → **OAuth client ID**, and choose the application type **Web
    application**. Give it a name such as `Modem`.

    Under **Authorized redirect URIs**, add the redirect URI you copied in step 1, exactly as Modem shows it.
  </Step>

  <Step title="Copy the client id and secret">
    Create the client and copy the **Client ID** and **Client secret**. The secret is shown once — if you lose it, create a new one
    rather than guessing.
  </Step>

  <Step title="Register Google in Modem">
    Back on the Modem SSO settings page, choose OIDC and enter:

    | Field             | Value                         |
    | ----------------- | ----------------------------- |
    | **Issuer**        | `https://accounts.google.com` |
    | **Client ID**     | The client id from step 4     |
    | **Client secret** | The client secret from step 4 |

    Modem reads Google's discovery document from the issuer to fill in the authorization, token, and JWKS endpoints, and always uses
    PKCE. Enter the email domain you are claiming at the same time.
  </Step>

  <Step title="Verify your email domain">
    Publish the DNS TXT record Modem shows on the SSO settings page and click verify. Sign-in is refused until this succeeds — see
    [Domain verification](/docs/enterprise/sso#domain-verification).
  </Step>
</Steps>

## Scopes

Modem requests three scopes:

| Scope     | Why                                          |
| --------- | -------------------------------------------- |
| `openid`  | Issues the id token carrying the `sub` claim |
| `email`   | The user's email address                     |
| `profile` | The user's name                              |

## The identity Modem stores

Modem stores the OIDC **`sub`** claim as the account identity. There is nothing to configure — Google's `sub` is already a stable, globally unique id for the user, and it does not change when someone's email address does.

<Info>
  [Directory Sync](/docs/enterprise/scim) matches directory users to Modem users by **`externalId`**, which has to be the **same value** Modem
  stores here — the `sub` claim — never the email address. Modem has setup guides for provisioning from [Okta](/docs/enterprise/scim-okta) and
  [Microsoft Entra ID](/docs/enterprise/scim-entra); Google Workspace provisioning is not covered by a guide yet.
</Info>

## Restricting who can sign in

Because the consent screen is **Internal**, only users in your Workspace can complete the flow, and Modem additionally requires the user's email domain to be the verified domain on the SSO settings page.

That still means any Workspace user who can reach the consent screen and whose address is on the verified domain can sign in. If you need a narrower set of people, restrict access to the app from the Google Workspace Admin console rather than relying on the Modem side.

## Testing the sign-in

Sign out of Modem, or use a private window, then:

1. Go to `https://app.modem.dev`
2. Click **Continue with SSO**
3. Enter your work email address, or your Modem organization slug
4. Complete the Google prompt

You should land back in Modem signed in. A user who has never used Modem before gets an account and joins as a **member**, unless they had a pending invitation carrying a different role.

<Warning>
  Start from the Modem sign-in page. Modem accepts **SP-initiated** sign-in only, so launching from an app tile or a bookmarked Google URL
  is rejected with "Start single sign-on from Modem". This is the single most common support question — it is worth telling your team up
  front.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Google reports redirect_uri_mismatch">
    The redirect URI registered on the OAuth client does not match Modem's exactly. Copy it again from the SSO settings page — it ends
    in your organization's provider id, `org-<id>`, and Google compares the whole string character for character, including the
    scheme and any trailing characters.
  </Accordion>

  <Accordion title="Single sign-on is not finished being set up">
    The domain has not been verified yet. Publish the DNS TXT record from the SSO settings page and click verify. DNS can take minutes
    to hours to propagate; retrying is safe.
  </Accordion>

  <Accordion title="No single sign-on provider for that address">
    The address typed at **Continue with SSO** is not on the verified domain. Personal Google accounts, and Workspace users on a
    secondary domain you have not verified, will not resolve to your provider.
  </Accordion>

  <Accordion title="Google says the app is blocked or the user is not allowed">
    The consent screen is **Internal**, so users outside your Workspace are refused by Google before the flow reaches Modem. Check the
    user's account, and any app access restrictions set in the Google Workspace Admin console.
  </Accordion>

  <Accordion title="The client secret was rotated">
    Modem holds the secret it was given, so rotating it in Google Cloud breaks the exchange. Enter the new secret on the Modem SSO
    settings page.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Enterprise SSO" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/shield.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=ee1ca3093fcbdf45ec5dc1a74652bed6" href="/docs/enterprise/sso" width="24" height="24" data-path="icons/shield.svg">
    Requirements, domain verification, and sign-in behaviour.
  </Card>

  <Card title="Team Management" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/users.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=32a2de5620a3659206db1c3d1aff5a06" href="/docs/features/team-management" width="24" height="24" data-path="icons/users.svg">
    Roles, invitations, and auto-join.
  </Card>
</CardGroup>