Google Workspace

Connects ZombieLicenseHunter to Google Workspace to sync directory users and license data via the Admin SDK Directory API, using either an OAuth client that you create in your own Google Cloud project or a service account with domain-wide delegation.

The two authentication methods:

• OAuth 2.0 (default): you create an OAuth client in your own Google Cloud project, paste its Client ID and Client Secret into the add-integration form, and a Workspace super admin consents in the browser. The refresh token Google returns is encrypted and used for every later sync.
• Service Account with domain-wide delegation: you create a service account, authorise it domain-wide in the Workspace Admin console, and paste its JSON key into the form together with the super admin it acts as. No browser consent is involved.

Both methods request the same two read-only scopes:

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

Prerequisites

1. A Google Workspace super admin account for the domain you want to sync. The Admin SDK resolves the customer from the signed-in or impersonated user, so a non-admin or personal Google account is refused with HTTP 403.
2. A Google Cloud project with the Admin SDK API enabled.
3. For OAuth 2.0: an OAuth 2.0 Client ID of type Web application in that project, with ZombieLicenseHunter's callback registered as an authorized redirect URI. The add-integration form prints the exact redirect URI for your instance.
4. For a service account: a service account in that project with a downloaded JSON key, authorised for domain-wide delegation.

Step 1: Enable the Admin SDK API

1. Go to console.cloud.google.com and create a new project (or select an existing one).
2. Navigate to APIs & Services → Library.
3. Search for Admin SDK API and click Enable.

Method 1: OAuth 2.0 (default)

Step 2: Configure the OAuth consent screen

1. Navigate to APIs & Services → OAuth consent screen.
2. Choose Internal so only accounts in your Workspace organization can consent.
3. Add the two scopes listed above.

Step 3: Create the OAuth client

1. Navigate to APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Web application.
3. Under Authorized redirect URIs, add:

   https://<your-zombielicensehunter-host>/integrations/google/callback
   

   The add-integration form shows this URI filled in for your instance once you select Google Workspace.
4. Click Create and copy the Client ID and Client Secret.

Step 4: Connect in ZombieLicenseHunter

1. Navigate to Integrations → Add Integration and select Google Workspace. Set Category to Directory.
2. Leave Authentication Method on OAuth 2.0.
3. Paste the Client ID and Client Secret from Step 3.
4. Click Save Integration. You are redirected to Google.
5. Sign in with the super admin account from the prerequisites and grant the two read-only scopes. Google redirects you back and the integration is created as active with its first sync queued.

The connected account's email domain must match the domain of the ZombieLicenseHunter user performing the connection; otherwise the callback fails with "you can only connect accounts from your organization's domain".

Method 2: Service Account with domain-wide delegation

Step 2: Create the service account and key

1. Navigate to IAM & Admin → Service Accounts → Create Service Account. No project roles are needed.
2. Open the new service account, go to Keys → Add Key → Create new key, choose JSON, and download the key file. Keep it safe; it contains a private key.
3. Note the service account's Unique ID (a long number). It is also the client_id value inside the key file.

Step 3: Authorise domain-wide delegation

1. In the Google Workspace Admin console, open Security → Access and data control → API controls → Domain-wide delegation.
2. Click Add new, enter the service account's client ID from Step 2, and paste the two scopes listed at the top of this page, comma-separated.
3. Click Authorize.

Step 4: Connect in ZombieLicenseHunter

1. Navigate to Integrations → Add Integration and select Google Workspace. Set Category to Directory.
2. Under Authentication Method, choose Service Account (Domain-Wide Delegation). The form lists the exact scopes to authorise.
3. Paste the whole JSON key file into Service Account Key (JSON).
4. In Delegated Super Admin, enter the email address of the Workspace super admin the service account will act as.
5. Click Save Integration. Saving checks that the key file is a JSON object, encrypts it, and queues the first sync.

Everything else is first exercised by that sync: a missing Admin SDK API, a client ID that is not authorised domain-wide, a scope mismatch, or a delegated user who is not a super admin all appear as a sync error on the integration page rather than at save time.

To rotate the key later, add the integration again with the new key and delete the old one; the edit page does not accept a new key file.

What Gets Synced

Troubleshooting

Google shows "redirect_uri_mismatch" The redirect URI registered on the OAuth client does not exactly match the one the form displays. Compare scheme, host, port and path; there is no trailing slash.

403 "Not Authorized to access this resource/api" after connecting The account chosen on Google's "Choose an account" screen (or the delegated super admin, for a service account) is not a Workspace super admin, or the Admin SDK API is not enabled on the project that owns the credentials. Disconnect, and reconnect in a private window so the right account is offered.

"Access denied: you can only connect accounts from your organization's domain" The Google account used for consent belongs to a different domain than your ZombieLicenseHunter login. Use an admin account on the same domain.

Service account sync fails with "unauthorized_client" The service account's client ID is not authorised for domain-wide delegation with exactly the two scopes above. Re-check the entry under API controls → Domain-wide delegation; the scopes must match character for character.

Sync stops working weeks later with an authorization error The refresh token was revoked (admin changed the password, removed the app under Security → Third-party apps, or the consent screen is still in Testing mode, whose tokens expire after 7 days). Publish the consent screen or keep it Internal, then use Reconnect on the integration.

No users synced after successful connection Confirm the Admin SDK API is enabled on the correct GCP project and that the admin who consented (or is impersonated) has access to the organizational units you expect to sync.