> ## Documentation Index
> Fetch the complete documentation index at: https://modem.ai/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

Setup runs in two passes, like the SAML providers, because each side needs a value the other one generates: Google issues the client id and secret Modem needs, and Modem only shows the redirect URI Google needs once the provider is registered.

<Steps>
  <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`.

    Leave **Authorized redirect URIs** empty for now, or put `https://app.modem.dev` there as a placeholder. You replace it in step 5
    with the redirect URI Modem generates.
  </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">
    In the [Modem dashboard](https://app.modem.dev), go to **Settings** → **Single Sign-On**, choose **OpenID Connect (OIDC)**, and enter:

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

    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="Paste Modem's redirect URI back into Google">
    The SSO settings page now shows the **redirect URI** for your organization, which looks like
    `https://app.modem.dev/api/auth/sso/callback/org-<id>`. Copy it, return to the OAuth client in the Google Cloud Console, and add
    it under **Authorized redirect URIs**, exactly as Modem shows it. Remove the placeholder if you used one, and save.
  </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 these three scopes and no others:

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

## Teams that already sign in with Google

Most teams arriving here have been using the **Continue with Google** button, and that is the easy case: those people keep the same Modem account, the same organization membership, the same role, and everything already in it.

The first time each of them signs in through **Continue with SSO**, Modem moves them onto single sign-on automatically. There is nothing for you to do — no accounts to re-invite, nothing for them to disconnect first — and your team can move across one at a time, at whatever pace suits your rollout.

Moving across is the point, and it settles per person: from then on, single sign-on is simply how that person signs in, and **Continue with Google** no longer signs them in. That does not wait on anything you switch on — each person's own first single sign-on is what moves them.

<Note>
  Someone who has not signed in through **Continue with SSO** yet can still use either route, and both land in the same account. It is
  their first single sign-on that moves them, not a setting.
</Note>

## Restricting who can sign in

Because the consent screen is **Internal**, only users in your Workspace can complete the flow.

Modem does not refuse a Workspace user whose address is off the verified domain: they join as a **member**, and Modem never marks that address as verified.

If you need a narrower set of people, restrict access to the app from the Google Workspace Admin console, or connect [Directory Sync](/docs/enterprise/scim#enforcing-sso-for-provisioned-users) so that only people your directory lists as active can sign in.

## Testing the sign-in

<Note>
  Testing with your own account moves your account across, exactly as it would anyone else's: from then on you sign in with **Continue
  with SSO**, and **Continue with Google** no longer signs you in. That is the intended outcome rather than a side effect of testing, and
  nothing else about your account changes — but you will be the first person it happens to, so it is worth expecting.
</Note>

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. Launching from an app tile or a bookmarked Google URL
  ends on a generic "We could not complete authorization" page, not the "Start single sign-on from Modem" message SAML providers show.
  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="Your account is already connected another way">
    A member who previously signed in with **Continue with Google** is normally moved onto single sign-on automatically, but a few
    cases are held back deliberately. The person cannot clear this themselves and does not need to change anything. Contact
    [support@modem.dev](mailto:support@modem.dev) with the error code shown on their screen, `account_provider_conflict`, and we will
    finish the move.
  </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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.