Google Workspace

Description

The Google Workspace connector uses the Google Admin SDK Directory API to discover user accounts, groups, group memberships, and admin role assignments within a Google Workspace domain. It authenticates via OAuth 2.0 domain-wide delegation, allowing a GCP service account to act on behalf of a super-admin without interactive login — no Google Workspace SDK is required on the OrbisID server.

System Type Classification

Field	Value
System Type	Directory Service
Default Scan Priority	10 (scanned first)

Version Support

OrbisID Edition	Supported
Community	No
Pro	Yes
Enterprise	Yes

Google Workspace scanning requires a Pro or Enterprise licence.

Supported Protocol

Protocol	Port	Notes
Google Admin SDK REST API (HTTPS + OAuth 2.0 domain-wide delegation)	443 TCP	Scoped JWT bearer flow

What OrbisID Discovers

Data	Source
User accounts	GET /admin/directory/v1/users?customer=my_customer (paginated)
User status (active/suspended)	suspended property
Groups	GET /admin/directory/v1/groups?customer=my_customer (paginated)
Group memberships	GET /admin/directory/v1/groups/{key}/members
Admin roles	GET /admin/directory/v1/customer/my_customer/roles
Admin role assignments	GET /admin/directory/v1/customer/my_customer/roleassignments
Super-admin flag	isAdmin property on user

Connection Requirements

GCP Service Account with Domain-Wide Delegation

Google Workspace scanning uses domain-wide delegation, which allows a GCP service account to impersonate a Workspace super-admin. This is the standard method for server-to-server access to Google Workspace APIs.

Step 1 — Enable the Admin SDK API:

In the GCP Console, navigate to APIs & Services → Library, search for Admin SDK API, and click Enable on the service account's project. This is required independently of domain-wide delegation — without it, every request (including Test Connection) fails with 403: Admin SDK API has not been used in project ... or it is disabled.

Step 2 — Create a GCP Service Account:

1. In the GCP Console, navigate to IAM & Admin → Service Accounts
2. Click Create Service Account (e.g., orbisid-ws-scanner)
3. No GCP IAM roles are needed — click through to Done
4. Click the service account → Keys → Add Key → Create new key → JSON
5. Download the JSON key file — note the client_id, private_key, and private_key_id fields

Step 3 — Enable Domain-Wide Delegation:

1. In the GCP Console, open the service account → Advanced settings
2. Click Enable domain-wide delegation — note the OAuth client ID (numeric)
3. In the Google Workspace Admin Console, navigate to Security → Access and data controls → API controls → Domain-wide delegation
4. Click Add new and enter:
   • Client ID: The OAuth client ID from step 2
   • OAuth Scopes:

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

Credential Mapping

OrbisID Field	Google Workspace Value
credential.username	Service account email (e.g., orbisid-ws-scanner@project.iam.gserviceaccount.com)
credential.privateKey	Service account private key (PEM — the private_key from the JSON key file)
credential.domain	Private key ID (private_key_id from the JSON key file, optional)

Use the Private Key field, not Password

The PEM key goes in the Credential form's Private Key field (a multi-line box — the same one used for Linux SSH keys), not Password. Password renders as a single-line masked input, which silently strips line breaks out of anything multi-line pasted into it; Private Key is a plain multi-line textarea, so the key's line structure survives.

Pasting the private_key value from the JSON file

Opened as plain text, the downloaded JSON key file's private_key value looks like this:

"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n"

Those \n are literal backslash-n characters — how JSON encodes a line break in a string — not actual line breaks. Pasting that text as-is into the Private Key field used to fail with an opaque Illegal base64 character 5c error; OrbisID now automatically converts those literal \n sequences into real line breaks when the credential is saved, so pasting the JSON value verbatim works either way. If you're instead typing the key out from a JSON-aware viewer/editor (which usually renders \n as real line breaks already), that also works unchanged.

System Attributes

Attribute	Required	Description
googleDomain	Yes	Primary Workspace domain (e.g., company.com)
googleDelegatedAdmin	Yes	Super-admin email to impersonate (e.g., admin@company.com)

Network Requirements

Requirement	Detail
Outbound HTTPS	OrbisID server (or On-Premise Agent) must reach oauth2.googleapis.com and admin.googleapis.com on port 443

Configuration Steps

1. Complete the GCP service account and domain-wide delegation setup above
2. Download the JSON key file and extract private_key and private_key_id
3. Create a Credential in OrbisID:
   • Username: Service account email
   • Private Key: Private key PEM, including the full -----BEGIN PRIVATE KEY----- block (paste the JSON file's private_key value as-is — see the tip above)
   • Domain: Private key ID (optional)
   • Leave Password blank
4. Navigate to Systems → Add System
5. Fill in the fields:

Field	Value
Name	Descriptive name (e.g., Google Workspace – company.com)
Hostname	admin.googleapis.com (used for reference)
OS Type	Google Workspace
System Type	Directory Service
Credential	The service account credential created above

6. In the Connection Attributes section, fill in:
   • Workspace Primary Domain (googleDomain) → your Workspace primary domain
   • Delegated Admin Email (googleDelegatedAdmin) → a super-admin email address
7. Click Test Connection to verify delegation
8. Click Save

Delegated Admin Selection

The googleDelegatedAdmin email must belong to a super-admin in the Workspace domain. Use a dedicated admin account for OrbisID rather than a personal admin account to avoid disruption if the personal account changes.

Domain-Wide Delegation Scope

Domain-wide delegation grants broad access. Use the minimal OAuth scopes listed above. Do not add write scopes such as admin.directory.user (without .readonly) unless required.

Real-Time Account & Entitlement Events

Beyond periodic full scans, OrbisID can poll the Admin SDK Reports API on a short interval to detect account and group-membership changes near-real-time — requires the admin.reports.audit.readonly OAuth scope in addition to what a normal scan needs. Opt-in Admin SDK push notifications (users.watch) are also supported, though OrbisID does not create or renew the channel itself — you create it yourself and point it at OrbisID's webhook URL. See Real-Time Events — Pro/Enterprise only.

Troubleshooting

Symptom	Likely Cause	Resolution
Scan fails: "googleDomain is required"	googleDomain attribute not set	Add googleDomain in system attributes
Scan fails: "googleDelegatedAdmin is required"	googleDelegatedAdmin attribute not set	Add googleDelegatedAdmin in system attributes
401 Unauthorized / invalid_grant	Service account or delegation misconfigured	Re-check the GCP OAuth client ID in the Workspace Admin Console delegation settings
403 — "Admin SDK API has not been used in project ... or it is disabled"	Admin SDK API not enabled on the service account's GCP project	Visit the URL in the error message (or APIs & Services → Library → Admin SDK API in the GCP Console) and click Enable; wait a minute or two, then retest
403 Not Authorized to Access	Domain-wide delegation not granted for these scopes	Verify all three read-only scopes are added in the Workspace Admin Console
No users returned	Delegated admin cannot list users	Ensure the googleDelegatedAdmin is a super-admin; verify the user.readonly scope is granted
Scan fails: "private key PEM (credential's Private Key field) is required"	The key was pasted into Password instead of Private Key, or left empty	Move the PEM into the credential's Private Key field
Illegal base64 character 5c / "Private key contains literal '\n' characters instead of real line breaks"	A credential saved before this connector auto-normalized the key still has the literal \n escapes baked into its stored value	Open the credential and click Save again (no changes needed) — this re-applies the fix. New credentials are normalized automatically on first save
"Private key is not valid Base64..." / "Private key data does not decode as a valid PKCS#8 RSA key"	The pasted key was truncated, re-wrapped, or edited	Re-download the JSON key file and paste the private_key value again, unmodified, including the full -----BEGIN/-----END block, into the Private Key field