Skip to content
Dashboard
Theme
Theme

Google Workspace OAuth directory sync

Set up directory sync from Google Workspace

View Markdown

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

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.

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

  2. 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, directory_source_oauth_expired, directory_source_workspace_required, directory_source_admin_required, directory_source_oauth_confirm_required, directory_source_oauth_domain_unverified

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

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

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

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

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