Domain-wide delegation for read-only directory access: a step-by-step setup

This is the most technical part of getting Workspace Sync running. It happens once. After it’s in place, your directory is connected and the system runs itself.

The step-by-step instructions live in Help, where they are kept current with the product: Connect Google Workspace. That page remembers which steps you’ve done, so you can stop and come back. This post explains why the connection works the way it does, so the steps make sense when you get there.

What you’re actually setting up

Two things need to exist:

1. A Google Cloud service account. A non-human Google identity, with its own key, that Workspace Sync uses to authenticate. It belongs to you, lives in your Google Cloud project, and you can revoke it in one click.
2. Domain-wide delegation. Your authorisation, given as a Google Workspace super admin, for that service account to act on behalf of an admin in your Workspace, limited to one permission.

The one permission

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

That scope lets the service account list users and read their directory profile: name, email, phone, title, department, photo. It cannot create, edit or delete anything, cannot read mail, files or calendars, and cannot see passwords or sign-in data. It is the only scope Workspace Sync needs. The setup guide offers one optional extra, admin.directory.customer.readonly, which lets it read your company name from the Workspace billing profile; it is read-only too, and you can leave it out. If a setup guide anywhere tells you to add anything else, it isn’t ours.

Why a service account and not “Sign in with Google”

A person’s sign-in expires, changes when they leave, and carries every permission that person has. A service account with delegation is narrower and more durable: it has exactly one job, it survives staff changes, and its key is something you hand over and can take back. That is also why Workspace Sync stores the key encrypted and cannot show it to you afterwards. You hold the original.

What can go wrong

Almost every failed first sync is one of five things: the Admin SDK API isn’t enabled, the scope isn’t copied exactly, the key was saved by someone who isn’t a super admin, Google hasn’t propagated the authorisation yet, or the key was pasted incompletely. Help lists them with the fix for each: Fix “Sync failed”.

Ready?

Open the guide and take it one step at a time: Connect Google Workspace. About 15 minutes, and your directory is on its way to every phone.