RingSyncRingSync

Configure Google Workspace

Overview

RingSync reads your Google Workspace directory through the Admin SDK Directory API, read-only. Two enrollment methods are supported:

  • Method B — Dedicated Service Account + Domain-Wide Delegation (recommended) — you create and own a service account in your own GCP project, authorize it, and provide its JSON key. Works immediately, with no Google verification required. The key stays under your control and is revocable at any time.
  • Method A — Admin OAuth ("Sign in with Google") — best UX (one button) but requires Google to verify the consent screen (the Directory scopes are sensitive) before external customers can use it.
Which method should I pick?

Start in production with Method B (no Google verification needed). Launch the Method A OAuth verification in the background if you want the one-button experience later.

Prerequisites

  • A Super Admin account in the Google Workspace domain (to authorize domain-wide delegation, or to consent in OAuth).
  • For Method B: access to a Google Cloud project where you can create a service account and a key.
  • A RingSync back-office account.

Directory scopes used (read-only)

Both methods use the same read-only Directory scopes:

https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.group.readonly
https://www.googleapis.com/auth/admin.directory.group.member.readonly

See Google permissions for details, auditing and revocation.

Method B — Dedicated Service Account + Domain-Wide Delegation

The service account lives in your GCP project. RingSync only receives the JSON key (encrypted in its vault) and uses it read-only.

B.1 — Create the service account (your GCP project)

  1. Go to Google Cloud Console → create or choose a project → APIs & Services → Library → enable Admin SDK API.
  2. Go to IAM & Admin → Service Accounts → Create service account (for example, ringsync-sync). No project IAM role is required.
  3. Open the service account → Keys → Add key → Create new key → JSON → download the file and keep it confidential.
  4. Note the numeric Client ID of the service account (about 21 digits): the "client_id" field in the JSON, or Unique ID in the service account details.
Enabling key creation

If an org policy blocks key creation (constraints/iam.disableServiceAccountKeyCreation), lift it only on your project (or re-enable it right after), never org-wide.

B.2 — Authorize the delegation (Google Admin console)

  1. Go to admin.google.com → Security → API controls → Domain-wide delegation → Add new.

  2. Client ID = the numeric Client ID from step B.1.4.

  3. OAuth scopes (one line, comma-separated):

    https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly

  4. Click Authorize.

B.3 — Enter the configuration in RingSync

In the RingSync back office, create a new space → Google Workspace → Service Account (DWD) → fill in:

  • Domain — for example acme.com.
  • Admin email to impersonate — an existing Workspace admin who can read the directory (a super admin works). The service account acts "as" this person.
  • Service Account key (JSON) — paste the contents of the file downloaded in B.1.3. It is encrypted in the vault and never re-exposed.

Click Test connection to validate access, then Create the space to provision and populate the access grants.

B.4 — Security notes for your sysadmin

  • You keep control: the service account is in your GCP project; you can revoke it at any time (delete the key in GCP, or remove the domain-wide delegation entry). Access is recorded in Google Audit logs.
  • Read-only: the service account can do nothing outside the three read-only Directory scopes — no mail, no Drive, no write. Domain-wide delegation is scope-by-scope.
  • Impersonated admin: an existing admin who can read the directory is enough (no account to create). Optionally, impersonate a custom admin role limited to Users: Read + Groups: Read to reduce the blast radius (a custom role consumes no license).
  • On the RingSync side: the key is stored encrypted in the vault, never in clear text. Plan a periodic rotation (regenerate the key on your side, re-paste it in the back office).

Method A — Admin OAuth ("Sign in with Google")

This method requires a Google Cloud project with an External consent screen carrying the sensitive Directory scopes.

A.1 — Configure the OAuth consent screen (once)

  1. Google Auth Platform → Audience → choose External (or Internal to test only on your own domain).
  2. Fill in the app name, support email, authorized domain, logo, and privacy policy link.
  3. Under Scopes, add the three Directory scopes (they are marked sensitive).
  4. While the app is unverified, only the test users you add here (or Internal mode on your own domain) can consent. For external customers, Submit for verification (scope justification, demo video). The Directory scopes are sensitive (consent-screen verification) and not restricted, so in principle no third-party security audit is required.
Verification takes time

Verification of a sensitive consent screen can take several weeks. Use Method B in the meantime.

A.2 — Create the OAuth Web client (once)

  1. Google Auth Platform → Clients → Create client → Web application.

  2. Under Authorized redirect URIs, add exactly:

    https://<backoffice-domain>/api/tenants/google/install-callback
http://localhost:3002/api/tenants/google/install-callback

    These must match NEXT_PUBLIC_APP_URL.

  3. Set the back-office environment variables:

    GOOGLE_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=xxxx

A.3 — Enter the configuration in RingSync

In the back office, create a new space → Google Workspace → Sign in with Google → the admin signs in and consents to the Directory scopes. RingSync stores the refresh token (encrypted in the vault) and provisions the space. The signed-in admin becomes the identity used to read the directory.

Scoping which users are synced

Google has no equivalent of Entra's appRoleAssignedTo. The set of authorized seats is set in the space settings ("Authorized seats": the whole domain, or specific Google groups).

Group filtering is Pro and above

Restricting sync to specific Google groups (and excluding groups) is a Pro and above feature. See Group selection & exclusion.

Verify the connection

  1. In the RingSync back office, use Test connection (Method B) or confirm the OAuth sign-in succeeded (Method A).
  2. Confirm the access grants list is populated after creating the space.
  3. From a phone, open the mobile app, tap Continue with Google, and confirm the directory appears and a first sync succeeds.

Troubleshooting

  • All directory calls fail with 403 — the Admin SDK API is not enabled on the project. Enable it under APIs & Services → Library.
  • "unauthorized_client" on sync — the domain-wide delegation entry is missing or its scopes don't match exactly. Re-check the Client ID and the comma-separated scope list in the Admin console.
  • Verification blocks external admins (Method A) — the consent screen is unverified. Add them as test users, or use Method B.
  • {{TO COMPLETE: exact error shown in the back office when the impersonated admin lacks directory read rights}}
Was this page useful?
Report what is missing →
← Previous
Graph permissions
Next →
Google permissions