setup

Google Workspace

Purpose

Ingests Workspace users, groups, third-party OAuth apps, and devices through OAuth.

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

tip

Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.

Required Fields

Field Secret? Description
googleworkspace_client_id No OAuth Client ID (Web application type)
googleworkspace_client_secret Yes OAuth Client Secret
googleworkspace_refresh_token Yes Refresh token from the OAuth consent flow
googleworkspace_token_uri No OAuth token endpoint (default suffices in most cases)

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.

Scope What Subimage uses it for
admin.directory.customer.readonly Workspace tenant metadata
admin.directory.user.readonly Users, aliases, and account status
cloud-identity.groups.readonly Groups, memberships, and ownership
admin.directory.user.security (optional) Third-party OAuth apps that users authorized, with each app's scopes
cloud-identity.devices.readonly (optional) Managed devices and assigned users; Enterprise or Premium tenants only

Google offers no read-only version of admin.directory.user.security. The scope also allows an administrator to revoke a user's tokens and sign the user out. Subimage only lists token metadata with it, which shows the third-party apps that have access to your users' Gmail, Drive, and other data. If you don't grant the scope, turn off googleworkspace_sync_oauth_apps in step 5. Subimage then skips OAuth app inventory.

Setup Steps

Steps 1 to 3 happen in one Google Cloud project inside your Workspace organization. If you already connected the GCP module, its host project works.

  1. Enable the APIs. Enable Admin SDK API (admin.googleapis.com) and Cloud Identity API (cloudidentity.googleapis.com) in the project. Google attributes API calls to the project that owns the OAuth client, so they must be enabled there. This does not select the OAuth scopes; step 4 does.

    In the console, use APIs & Services → Library, or run:

    gcloud services enable admin.googleapis.com cloudidentity.googleapis.com --project=<PROJECT_ID>
  2. Configure the consent screen. Open https://console.cloud.google.com/auth/overview?project=<PROJECT_ID>. If it shows Google Auth Platform not configured yet, click Get started:

    • App Information: any App name (for example SubImage) and a User support email. A Google Group you manage works.
    • Audience: Internal. An External app in Testing status issues refresh tokens that expire after 7 days, which breaks the sync a week later.
    • Contact Information: an address Google can send project notices to.
    • Finish: agree to the Google API Services User Data Policy, click Continue, then Create.

    If the project already has a consent screen, open Audience and confirm User type is Internal. You do not need to add scopes under Data Access.

  3. Create the OAuth client. In Clients, click Create client:

    • Application type: Web application.
    • Name: anything, for example SubImage Google Workspace sync. Only the console shows it.
    • Authorized redirect URIs: click Add URI and enter https://developers.google.com/oauthplayground. Leave Authorized JavaScript origins empty.
    • Click Create, then copy the Client ID and Client Secret or click Download JSON. Google shows the secret only once.

    Google notes that a new client can take from 5 minutes to a few hours to take effect. If the next step fails with redirect_uri_mismatch or invalid_client, wait and retry.

  4. 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 3.
    • Leave the other settings at their defaults. Access type: Offline is what makes Google return a refresh token.
    • In Step 1, skip the API list and paste the scopes into the Input your own scopes field below it. The field is a single line, so the scopes must be separated by spaces; pasting one scope per line merges them into one invalid scope. For users, groups, and OAuth apps:
      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 also sync managed devices (requires Cloud Identity Premium or Workspace Enterprise), use this instead:
      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 https://www.googleapis.com/auth/cloud-identity.devices.readonly
    • To skip OAuth app inventory, delete https://www.googleapis.com/auth/admin.directory.user.security from the scopes you paste.
    • Click Authorize APIs and sign in with a Google Workspace administrator that can read customer details, users, and user OAuth token metadata. A super administrator is the simplest choice for validating the setup. The sync runs as this account, so use one that will stay active.
    • After you approve, the Playground returns to Step 2. If the Refresh token field is empty, click Exchange authorization code for tokens. Copy the Refresh token.
  5. 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 4 (or its AWS Secret ARN)
    • googleworkspace_token_uri — leave as default
    • googleworkspace_sync_oauth_apps — on by default. If the refresh token does not include admin.directory.user.security, turn it off.
    • googleworkspace_sync_devices — enable only if the refresh token includes cloud-identity.devices.readonly
  6. Save the module.

Troubleshooting

  • invalid_grant means the refresh token expired or was revoked. Common causes: the consent screen audience is External and in Testing (tokens last 7 days), the authorizing administrator was suspended or deleted, or the token was minted with the Playground's default credentials instead of your own OAuth client.
  • 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 googleworkspace_sync_oauth_apps is on but the refresh token does not include https://www.googleapis.com/auth/admin.directory.user.security, the sync fails with invalid_scope. Turn off googleworkspace_sync_oauth_apps, or get a new refresh token that includes the scope.
  • If a required scope is missing, Subimage will surface a config error with remediation steps.
  • 403 Not Authorized to access this resource/api means Google accepted the OAuth token but the account that authorized it cannot read the Admin Directory. Repeat the consent flow with a sufficiently privileged Workspace administrator (use a private window if multiple Google accounts are signed in), and confirm Admin SDK access is not restricted in the Admin console.

Migrating from gsuite

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