Google Workspace

Purpose

Ingests Workspace users, groups, and devices via OAuth.

For service-account delegation, use the legacy gsuite module instead.

Required Fields

OAuth access

SubImage inventories Workspace identities and access. It does not request access to Gmail, Drive, or Calendar data, and it does not modify Workspace resources.

Setup Steps

1. Create OAuth credentials. In Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID. Select Web application and add https://developers.google.com/oauthplayground as an authorized redirect URI. Note the Client ID and Client Secret.
2. Enable the APIs. In APIs & Services → Library, enable Admin SDK API and Cloud Identity API. This makes the APIs available to the Cloud project; it does not select the OAuth scopes used in the next step.
3. Get a refresh token via Google OAuth Playground:
   • Open the Playground in a new tab so the SubImage module setup remains open.
   • Click the gear icon → check Use your own OAuth credentials → paste the Client ID and Secret from step 1.
   • In Step 1, use Input your own scopes instead of selecting an Admin SDK category. Paste these four scopes:

     https://www.googleapis.com/auth/admin.directory.customer.readonly
     https://www.googleapis.com/auth/admin.directory.user.readonly
     https://www.googleapis.com/auth/admin.directory.user.security
     https://www.googleapis.com/auth/cloud-identity.groups.readonly

   • To sync managed devices, also add the following scope. It requires Cloud Identity Premium or Workspace Enterprise:

     https://www.googleapis.com/auth/cloud-identity.devices.readonly

   • Click Authorize APIs and sign in with a Workspace admin account.
   • In Step 2, click Exchange authorization code for tokens and copy the Refresh token.
4. In SubImage, fill in:
   • googleworkspace_client_id — the OAuth Client ID
   • googleworkspace_client_secret — the OAuth Client Secret (or its AWS Secret ARN)
   • googleworkspace_refresh_token — the refresh token from step 3 (or its AWS Secret ARN)
   • googleworkspace_token_uri — leave as default
   • googleworkspace_sync_devices — enable only if the refresh token includes cloud-identity.devices.readonly
5. Save the module.

Troubleshooting

• RefreshError: ('invalid_scope: Bad Request', ...) usually means the refresh token was minted for a different scope set than the one SubImage is requesting.
• The required scopes must match exactly, including https://www.googleapis.com/auth/cloud-identity.groups.readonly.
• If googleworkspace_sync_devices is enabled but the refresh token does not include https://www.googleapis.com/auth/cloud-identity.devices.readonly, SubImage will continue syncing users and groups and skip device inventory.
• If a required scope is missing, SubImage will surface a config error with remediation steps.

Migrating from gsuite

The OAuth approach does not require a service account or domain-wide delegation setup in Google Admin Console.