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 — 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 2 — 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.password	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)

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
   • Password: Private key PEM (include the full -----BEGIN RSA PRIVATE KEY----- block)
   • Domain: Private key ID (optional)
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. Add the required system attributes:
   • googleDomain → your Workspace primary domain
   • 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.

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 Access Not Configured	Admin SDK API not enabled	In GCP Console, enable Admin SDK API for the project
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
Private key error	Malformed PEM	Paste the entire private_key value from the JSON key file, including the -----BEGIN RSA PRIVATE KEY----- header and footer