Google Workspace

Walks you through creating the GCP service account and granting domain-wide delegation Hal needs to monitor Google Workspace audit logs and Alert Center notifications, by clicking through the customer’s GCP and Workspace consoles yourself.

Repeat this process for every Google Workspace tenant. A client may have one or more GWS tenants, each one needs its own service account.

You will need Super Admin access to each Google Workspace tenant.

Record the values as you go: the key file and the super admin are what you give Hal, and the table at the end lists them.

Hal uses a GCP service account with domain-wide delegation to read each tenant’s Google Workspace audit logs and Alert Center notifications.

Step 1: Create a GCP Project

1. Sign in to the GCP Console (console.cloud.google.com ) as an admin for this Google Workspace tenant
2. Create a new project:
   • Project name: hal-siem-log-collector
3. Select the new project from the project dropdown at the top of the page. GCP does not auto-switch you into the project you just created, every step below will silently target the wrong project if you skip this.

Step 2: Enable Required APIs

1. Navigate to APIs & Services > Library
2. Search for Admin SDK API and click Enable
3. Search for Google Workspace Alert Center API and click Enable

Step 3: Create a Service Account

1. Navigate to APIs & Services > Credentials
2. Click Create Credentials > Service Account
   • Service account name: hal-log-collector
   • Skip the optional grant access steps
3. Click Done to create the service account
4. Click into the newly created service account
5. Copy the Unique ID (numeric Client ID) from the details page, you’ll need this for domain-wide delegation
6. Go to the Keys tab
7. Click Add Key > Create New Key > JSON

   • If you see “Service account key creation is disabled”, the tenant’s GCP organization enforces the iam.disableServiceAccountKeyCreation policy. The admin who overrides it must hold the Organization Policy Administrator role (roles/orgpolicy.policyAdmin ) at the organization level.

     Note

     Keep the GCP Console resource picker (top of page) on the organization throughout the steps below, not a project. IAM at project scope doesn’t show org-level roles like Organization Policy Administrator (a search returns “No matching roles found”), and the Organization Policies page at project scope hides org-wide constraints. Clicking into IAM or principal screens can silently reset the picker to a project; recheck it before every role-picker or policy-edit action.

   • If they don’t yet have that role, attempting the override produces a follow-on error: “The following permissions are required to edit organization policies: orgpolicy.policy.get, orgpolicy.policies.create, orgpolicy.policies.delete, orgpolicy.policies.update.” A Cloud Identity Super Admin can grant the role to themselves or another principal:

     1. In the GCP Console, switch the resource picker at the top of the page to the organization (not a project), then navigate to IAM & Admin > IAM
     2. Find the target principal (your Super Admin email is typically already listed) and click into them, then click Add another role, assign Organization Policy Administrator, and Save.
        • If the principal isn’t listed yet, click Grant Access at the top of the page instead, enter the email, assign the role, and Save.
        • If “Organization Policy Administrator” doesn’t appear in the role picker, the resource picker at the top of the page has reverted to a project. Switch it back to the organization, return to IAM, and re-open the role picker. The role list at project scope doesn’t include it.
     3. Allow ~1 minute for propagation, then refresh

   • Once the role is in place, fix the policy at the scope that’s enforcing it:

     1. Navigate to IAM & Admin > Organization Policies
     2. Search for iam.disableServiceAccountKeyCreation and click into the policy
     3. Click Manage Policy. Either of these works depending on what’s enforcing:
        • Inherit parent’s policy, if a child scope (e.g. the hal-siem-log-collector project) is overriding the parent to enforce, switching to inherit drops the override so the scope follows the parent. Works when the parent doesn’t enforce.
        • Customize with Enforcement: Off, explicitly disables at this scope regardless of what the parent does. Works in all cases, including when the parent itself enforces.
     4. Save

   • Return to the service account’s Keys tab and retry step 7.

8. The JSON key file downloads automatically, keep this file safe
9. Name the file after the tenant’s domain (e.g., example-com-sa-key.json) so you can tell them apart

Step 4: Grant Domain-Wide Delegation

1. Sign in to the Google Workspace Admin Console (admin.google.com ) as a Super Admin for this tenant

2. Navigate to Security > Access and data control > API controls

3. Click Manage Domain Wide Delegation

4. Click Add new

5. Configure:

   • Client ID: paste the numeric ID from Step 3.5

   • OAuth scopes: copy the comma-separated string in the code block below and paste into the OAuth scopes field. Six scopes:

     https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/apps.alerts,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.group.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly

     What each scope is for. All are read-only except apps.alerts, the Alert Center’s only scope, which can also change alerts; Hal only reads with it, and never writes to your Workspace:

     Scope	Purpose
     admin.reports.audit.readonly	Read audit-log events (logins, file shares, admin changes, etc.), the primary signal Hal triages
     apps.alerts	Read Alert Center alerts (Google’s own security flags) so Hal can correlate them with audit events
     admin.directory.customer.readonly	Read your Workspace customer ID, used to route audit events to your organization in Hal’s pipeline (immutable per Workspace)
     admin.directory.user.readonly	Read user profiles; Hal lists users once a day to count billable identities (every user who is not suspended or archived, mailbox or not) and to confirm the delegation at onboarding
     admin.directory.group.readonly	Grants read access to your Workspace’s groups and their members
     admin.directory.domain.readonly	Read your Workspace’s verified domains, so Hal knows which of your addresses are yours

     Grant these six and nothing more. Hal confirms that each is granted, but he cannot see other scopes the delegation grants or the service account’s project roles, so keeping the delegation to these six is yours.

6. Click Authorize

Record these credentials for this tenant

Then move to the next tenant and repeat from Step 1.

Connecting the tenant to Hal

In the portal chat, tell Hal you created the service account for the client. He opens a paste box for that client on Settings → Google Workspace, open for 24 hours: choose the key file, enter the email of the super admin Hal acts as, and Save. The key goes in that box, never in chat, and Hal holds it for an hour, so tell him done within it; after that, give it to him again first.

Before anything is stored, Hal asks Google about each of the six scopes, acting as that admin. admin.directory.user.readonly and admin.directory.customer.readonly are the two he cannot connect without: a delegation missing any other connects with a partial read, and he names what is missing. A delegation entry can take up to 24 hours to take effect at Google, so if he finds none of the scopes granted just after you added it, tell him done again later, giving him the key and the admin again first once the hour has passed. He reads the Workspace’s name and domains, shows them to you, and stores it only after you confirm. Then ask him to start ingesting: the first cycle backfills 180 days of Workspace audit and Alert Center history.

To replace the key later, create a new one for the service account and ask Hal to rotate the Google Workspace service account key; you give it to him the same way.

Or connect the Workspace with Hal-assisted onboarding, which reads with Hal’s own service account and needs only the delegation entry.

Questions? Contact us.