Google Workspace

Sprooster reads your people from the Google Admin SDK Directory API: names, emails, titles, departments, managers, and org units. Read-only, always.

There are two ways in. Take the first one.

Connect in one click (recommended)

In Sprooster's Connect directory step (or Settings → Data sources → Google Workspace), hit Connect Google Workspace. Sign in as a Google Workspace super admin, approve the read-only directory access Google lists, and you're done. Sprooster lands back on the connect screen already connected. No Cloud console, no key file, no delegation screen. Thirty seconds.

Sign in as an admin. The account you approve with has to be able to read your directory: a super admin, or a delegated admin with user-management rights. A regular employee's account is turned away with "that Google account can't read the directory."

Sprooster stores the resulting grant (encrypted) and refreshes it on each sync, so the connection keeps working after you close the tab. To hand it off later (someone leaves, or you'd rather it ran as a role account), sign in again as the new admin and hit Reconnect Google Workspace; the new grant replaces the old one.

Set up a service account instead

Prefer a credential that belongs to no particular person, or your policy forbids admin OAuth grants? The original path still works, and it's under Set it up with a service account instead on the same card. Budget fifteen minutes, and you'll need the Google Cloud console plus a super admin on admin.google.com.

1. Create a service account

1. In the Google Cloud console, pick (or create) a project: sprooster-directory is fine.
2. Enable the Admin SDK API: APIs & Services → Library → Admin SDK API → Enable.
3. Go to IAM & Admin → Service Accounts → Create service account. Name it, skip the optional role grants (it needs no Cloud roles), and create it.
4. Open the account → Keys → Add key → Create new key → JSON. A key file downloads.

From that JSON file you'll use two values: client_email and private_key.

2. Grant domain-wide delegation

1. On the service account's Details page, copy its Unique ID (a long number). This is the OAuth client ID.
2. In admin.google.com, go to Security → Access and data control → API controls → Domain-wide delegation → Add new.
3. Paste the Unique ID as the Client ID, and grant exactly these scopes (comma-separated, all read-only):

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

3. Pick an admin to impersonate

Domain-wide delegation works by letting the service account act as a real admin. Choose a super admin account (a role account like it-admin@yourdomain.com beats a personal one: it survives people leaving). This is the Admin to impersonate field in Sprooster.

4. Paste three values into Sprooster

Open Set it up with a service account instead on the Google Workspace card:

Hit Test connection (you should see a count of your people and a few sample names), then Save connection.

Optional: hire dates and birthdays

Google's directory has no built-in hire-date or birthday fields, but it supports custom schemas. If you add one (Admin console → Directory → Users → More → Manage custom attributes) with date fields for hire date and birthday, tell Sprooster about it under Advanced endpoints & fields: set Custom schema name to the schema's name and the two field names to your attribute names. The sync then picks them up like any other field. Skip this entirely and everything else still works.

For your security review

The details an IT or security team usually wants before approving either path:

Auth flow — one-click. Standard OAuth 2.0 authorization-code flow against accounts.google.com, initiated only by a signed-in Sprooster admin and returned to a single registered redirect URI. Sprooster stores the resulting refresh token (encrypted, see below) and exchanges it for a one-hour access token on each sync. Revoke it any time from the admin's Google account or in Admin console → Security → API controls → App access control, and the sync stops.

Auth flow — service account. OAuth 2.0 JWT-bearer grant (urn:ietf:params:oauth:grant-type:jwt-bearer): Sprooster signs a short-lived RS256 assertion with your service account's key (iss = the service account, sub = the impersonated admin, exp = one hour) and exchanges it at https://oauth2.googleapis.com/token. No user sign-in, no refresh token.

Scopes. The same three read-only directory scopes either way, requested verbatim on every token: your grant is the ceiling. The one-click flow additionally requests openid, userinfo.email, and userinfo.profile, used once, to identify which admin consented and which Workspace customer they belong to:

admin.directory.user.readonly
admin.directory.orgunit.readonly
admin.directory.userschema.readonly

API surface. Reads against https://admin.googleapis.com/admin/directory/v1: users.list for your customer (paged; Google's Directory API has no delta cursor, so each sync is a full listing with idempotent upserts, and anyone no longer returned is pruned), plus org units and your custom schema definition when configured. No writes. No Gmail, Drive, Calendar, or login-audit scopes are requested, and delegation wouldn't permit them anyway.

Credential handling. Whichever credential you use (refresh token or private key) is encrypted app-side with AES-256-GCM before it's stored. The encryption key lives outside the database, so the database alone can't yield your credential, and it's write-only: the browser never receives it back. To rotate a service-account key, create a new one, paste it over, save, then delete the old key in Google Cloud. To rotate a one-click grant, reconnect (which replaces it) or revoke it in Google.

Throttling. Retry-After on 429/403 responses is honored with backoff.

Troubleshooting

One-click

• "That Google account can't read the directory" — you approved as a regular user. Sign out of Google, or use a separate profile, and approve as a super admin.
• "Google didn't hand back a lasting grant" — the consent screen was partially approved, or an existing grant was reused. Revoke Sprooster under your Google account's Third-party apps and connect again, approving every box.
• Sync stops working weeks later — someone revoked the grant, or the admin who approved it lost their admin rights or left. Reconnect as a current admin.

Service account

• unauthorized_client on test — domain-wide delegation is missing or the scopes don't match step 2 exactly (extra or missing scopes both fail).
• Invalid email or User ID — the impersonated admin isn't a real, active user, or isn't a super admin.
• Private key errors — the key must be the multi-line PEM from the JSON (with real line breaks, not the \n escapes); re-paste it from the file.
• New key, same errors for a few minutes — delegation and key changes can take a few minutes to propagate on Google's side.