# Google Workspace OAuth directory sync

<!-- Generated by scripts/generate.ts. Do not edit. -->

Connect Google in this setup as a Google Workspace admin, and we read your users and groups every few minutes.

:::caution[Verification]
Not yet verified on a real Google Workspace tenant. It was written from the public Google Workspace documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="account"></a>

### Choose the admin who connects

Connect as a Google Workspace admin whose role can read users, groups and group members, such as a super admin. The connection reads the directory as that admin, so keep the account active.

</li>

<li class="idp-step">

<a id="connect"></a>

### Connect Google

Select Connect Google. You can enter your Google Workspace domain, such as acme.com, so Google offers the right account; it is optional. A page from OhAuthCat names the organization this directory belongs to; check it, then select Continue. Your Google Workspace domain must already be verified for this organization. Sign in to Google as a Workspace admin whose role can read users and groups. A personal Gmail account has no directory and is refused. The connect link lasts 30 minutes; if it expires, select Connect Google again.

Fixes: [`directory_source_oauth_state_invalid`](/errors/directory_source_oauth_state_invalid/), [`directory_source_oauth_expired`](/errors/directory_source_oauth_expired/), [`directory_source_workspace_required`](/errors/directory_source_workspace_required/), [`directory_source_admin_required`](/errors/directory_source_admin_required/), [`directory_source_oauth_confirm_required`](/errors/directory_source_oauth_confirm_required/), [`directory_source_oauth_domain_unverified`](/errors/directory_source_oauth_domain_unverified/)

</li>

<li class="idp-step">

<a id="unverified"></a>

### Continue past the unverified app warning

While Google reviews our app, Google shows "Google hasn't verified this app". Select Advanced, then continue to OhAuthCat. The warning goes away once Google has verified the app.

</li>

<li class="idp-step">

<a id="approve"></a>

### Approve access

Google lists read-only access to your users, groups and group members. Leave every permission ticked and select Continue. If you untick one, the connection is refused with a missing permission error; select Connect Google again.

Fixes: [`directory_source_scope_missing`](/errors/directory_source_scope_missing/)

</li>

<li class="idp-step">

<a id="first-sync"></a>

### Wait for the first sync

The first sync starts right away. After that we read Google Workspace every 5 minutes; after a failure we wait longer between tries, up to an hour.

</li>

<li class="idp-step">

<a id="who"></a>

### Know who is synced

We read every user and group, with group members, on each sync. Users Google no longer returns are removed from the directory. To stop syncing, delete the directory. Connect Google is the recommended Google Workspace source. The Google Workspace (SCIM, beta) guide is the alternative, where Google pushes people only, never groups.

</li>

<li class="idp-step">

<a id="reconnect"></a>

### Connect again if access is removed

We keep the connection alive on our own. If the admin loses their role, their account is suspended or access is removed in the Google account settings, syncs stop with an invalid credentials error; select Connect Google again as a Workspace admin.

Fixes: [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/)

</li>

</ol>

## Sources

- [Control API access with domain-wide delegation (Google Workspace Admin Help)](https://support.google.com/a/answer/162106), read on 2026-10-29
