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.

When you’re done, you’ll enter these credentials directly on your MSP portal — one set per tenant.

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.

     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. Five 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

     What each scope authorizes (all read-only — Hal 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 — used to enrich audit events with 2SV status, suspended flag, org unit, and “is this user an admin?” context
     admin.directory.group.readonly	Read group memberships — used at investigation time to instantly answer “is this user in an admin group?”

6. Click Authorize

Record these credentials for this tenant

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

Activating monitoring

Once each tenant is set up, follow the tenant onboarding flow in your MSP portal to add the credentials. The portal validates them, starts log ingestion, and runs the first triage cycle within five minutes of activation. Historical data is backfilled up to 6 months.

Questions? Contact us.