# Google workspace
Connecting Google Workspace gives SureCloud read access to your domain's users, groups, admin roles, application authorisations, and audit logs. SureCloud authenticates using a service account with domain-wide delegation, which allows it to act on behalf of a designated admin account to call Google Workspace APIs across the domain without requiring individual user consent. SureCloud uses this access to monitor identity hygiene, access governance, data sharing policies, and administrative activity in a single continuous feed.
## What SureCloud monitors
| Google Workspace area | What SureCloud monitors |
| ------------------------------- | --------------------------------------------------------------------------------------- |
| **Google Directory** | Users, groups, organisational units, admin roles, and MFA enrolment status. |
| **Google Drive** | Shared drive configuration, external sharing settings, and DLP-relevant sharing events. |
| **Google Workspace Audit Logs** | Admin activity, login events, Drive audit events, and token authorisation logs. |
## Authentication and setup
SureCloud connects to Google Workspace using a GCP service account with domain-wide delegation. The service account is granted a specific set of Google Workspace API scopes by a Super Admin, giving SureCloud read-only access to the APIs it needs.
{% stepper %}
{% step %}
#### Create a GCP project and service account
In the [Google Cloud Console](https://console.cloud.google.com/), create a dedicated GCP project (or use an existing one) for SureCloud tooling.
Navigate to **IAM & Admin → Service Accounts → Create Service Account** and provide:
* **Name**: `surecloud-workspace`
* **Description**: SureCloud Google Workspace integration
Click **Create and Continue**, skip the optional role grant steps (roles are not required for this service account — access is controlled via domain-wide delegation), and click **Done**.
Note the service account's **email address** and **unique ID (client ID)** — you will need both.
{% endstep %}
{% step %}
#### Enable required APIs
In the GCP project, navigate to **APIs & Services → Enable APIs and Services** and enable the following:
* Admin SDK API
* Google Drive API
{% endstep %}
{% step %}
#### Generate a service account key
In **IAM & Admin → Service Accounts**, click the `surecloud-workspace` service account, go to the **Keys** tab, and click **Add Key → Create new key → JSON**. Download the key file.
{% hint style="warning" %}
Treat this JSON key file as a credential. Upload it to SureCloud immediately and delete the local copy. Rotate the key every 90 days and update it in **SureCloud → Integrations → Google Workspace → Edit Connection**.
{% endhint %}
{% endstep %}
{% step %}
#### Grant domain-wide delegation in the Google Workspace Admin Console
A Super Admin must complete this step. In the [Google Workspace Admin Console](https://admin.google.com/), navigate to **Security → Access and data controls → API controls → Manage domain-wide delegation → Add new**.
Enter:
* **Client ID**: the unique ID (not the email address) of the `surecloud-workspace` service account
* **OAuth scopes**: paste the following comma-separated list
```
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,
https://www.googleapis.com/auth/admin.directory.orgunit.readonly,
https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/admin.reports.usage.readonly,
https://www.googleapis.com/auth/drive.readonly
```
Click **Authorise**.
{% endstep %}
{% step %}
#### Enter credentials in SureCloud
In SureCloud, navigate to **Integrations → Google Workspace → Connect** and provide:
* **Admin email address**: a Super Admin or delegated admin account that the service account will impersonate
* **Service account key**: upload the JSON key file downloaded in step 3
* **Primary domain**: your Google Workspace primary domain (e.g. `yourcompany.com`)
Click **Test Connection**. SureCloud will validate the delegation and scope grants before saving.
{% endstep %}
{% endstepper %}
## Polling frequency
| Data type | Collection interval |
| ------------------------------ | ------------------- |
| Directory users and MFA status | 24 hours |
| Groups and group memberships | 24 hours |
| Admin role assignments | 24 hours |
| Drive sharing settings | 24 hours |
| Admin audit log events | 1 hour |
| Login audit log events | 1 hour |
| Drive audit events | 6 hours |
| Token audit events | 6 hours |
## Troubleshooting
Test Connection fails with "Client is unauthorized to retrieve access tokens using this method"
Domain-wide delegation has not been granted, or the service account client ID entered in the Admin Console is incorrect.
1. In the [Admin Console](https://admin.google.com/), go to **Security → API controls → Manage domain-wide delegation** and confirm the service account's **numeric client ID** (not the email address) is listed.
2. Confirm the full set of required OAuth scopes is present. A missing or incorrectly formatted scope will cause the delegation to fail for that scope.
3. Allow up to 15 minutes for delegation changes to propagate, then retry **Test Connection** in SureCloud.
Some OAuth scopes return "Insufficient Permission" errors despite being listed in domain-wide delegation
Each scope in the delegation must be entered exactly as specified — including the full URL. A trailing comma, space, or truncated URL will cause that scope to be rejected.
In the Admin Console, click **Edit** on the SureCloud delegation entry and compare each scope against the list in the setup steps above. Remove and re-add any malformed entries.
Service account key upload fails or Test Connection returns a key format error
The uploaded file must be the raw JSON key file downloaded from Google Cloud with no modifications. Confirm the file has not been re-encoded or reformatted.
If the key was lost before uploading, delete it in **GCP → IAM & Admin → Service Accounts → Keys** and generate a new one.
Audit log data is not appearing for secondary domains
Google Workspace audit logs are collected at the primary domain level. Users on secondary domains (aliases or additional domains) are included in the same audit log stream — no additional configuration is required. If specific users from secondary domains are missing from the Directory data, confirm they are active (not suspended) accounts.
## Service pages
* [Google Directory](broken://pages/5e9e08e372f419ddaacedf0599c4012f7620abdb)
* [Google Drive](broken://pages/c2a9885d0d6b71a5f3a23e36360e4aba25407fc9)
* [Google Workspace Audit Logs](broken://pages/dcc5496bbeaf0f1b5168f59ada34357d2b182f58)
Google domain-wide delegation guide Google Workspace Reports API docs
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/google-workspace.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.