Google Workspace

​

Setup Options

1. Automated Setup — Navigate to the Integrations section and use the automated setup flow. This requires an existing GCP project and admin permissions.
2. Manual Setup — Follow the step-by-step instructions below to configure the integration manually.

1. GCP Project & Service Account (shared prerequisite)
2. Alert Center > Pub/Sub > Clarion webhook (inbound alerts)
3. Admin SDK agent tools (optional — user lookup, suspend, revoke tokens, etc.)

​

Part 1: GCP Project & Service Account

​

Step 1: Create a Google Cloud Project (or use existing)

1. Go to Google Cloud Console
2. Click the project selector dropdown at the top > New Project
3. Enter a project name, select your organization > Create
4. Note your Project ID (e.g. clarion-workspace)

​

Step 2: Enable Required APIs

• Google Workspace Alert Center API (alertcenter.googleapis.com)
• Cloud Pub/Sub API (pubsub.googleapis.com)
• Gmail API (gmail.googleapis.com) — required for email investigation agent tools

​

Step 3: Create a Service Account

1. Go to IAM & Admin > Service Accounts > Create Service Account
2. Name: e.g. clarion-pubsub-push
3. Click Create and Continue > Done (no roles needed)
4. Click the new service account > Keys tab > Add Key > Create new key > JSON
5. Save the downloaded JSON file — you’ll need it for the Alert Center configuration script (Part 2) and optionally for Clarion Admin SDK credentials (Part 3)
6. Note the service account email (e.g. clarion-pubsub-push@your-project.iam.gserviceaccount.com)

​

Part 2: Inbound Alerts (Alert Center via Pub/Sub)

​

Step 1: Create a Pub/Sub Topic

1. Go to Pub/Sub > Topics > Create Topic
2. Name it (e.g. clarion-alerts, full name: projects/YOUR_PROJECT/topics/clarion-alerts)
3. Click Create
4. On the topic page, go to the Permissions tab > Grant Access
5. Add principal: alerts-api-push-notifications@system.gserviceaccount.com
6. Role: Pub/Sub Publisher
7. Click Save

​

Step 2: Enable Domain-Wide Delegation

1. Go to IAM & Admin > Service Accounts and click the service account from Part 1
2. Expand Advanced settings
3. Under Domain-wide Delegation, click Edit and enable Google Workspace Domain-wide Delegation
4. Note the Client ID (numeric, e.g. 107729743480716689292)

​

Step 3: Grant the Alert Center Scope in Google Workspace Admin Console

1. Go to Google Workspace Admin Console as a Super Admin
2. Navigate to Security > Access and data control > API controls
3. Click Manage Domain Wide Delegation
4. Click Add new
5. Enter:
   • Client ID: the numeric client ID from Step 2
   • OAuth Scopes: https://www.googleapis.com/auth/apps.alerts
6. Click Authorize

​

Step 4: Configure Alert Center to Publish to Pub/Sub

import json, urllib.request, urllib.error
from google.oauth2 import service_account
from google.auth.transport.requests import Request

creds = service_account.Credentials.from_service_account_file(
    '/path/to/your-service-account-key.json',
    scopes=['https://www.googleapis.com/auth/apps.alerts'],
    subject='admin@yourdomain.com'  # Must be a Super Admin
)
creds.refresh(Request())

req = urllib.request.Request(
    'https://alertcenter.googleapis.com/v1beta1/settings',
    method='PATCH',
    headers={
        'Authorization': 'Bearer ' + creds.token,
        'Content-Type': 'application/json'
    },
    data=json.dumps({
        "notifications": [{
            "cloudPubsubTopic": {
                "topicName": "projects/YOUR_PROJECT_ID/topics/clarion-alerts",
                "payloadFormat": "JSON"
            }
        }]
    }).encode()
)

try:
    resp = urllib.request.urlopen(req)
    print(resp.status, resp.read().decode())
except urllib.error.HTTPError as e:
    print(f"Error {e.code}: {e.read().decode()}")

• /path/to/your-service-account-key.json with the path to your service account JSON key
• admin@yourdomain.com with your Super Admin email
• YOUR_PROJECT_ID with your Google Cloud project ID

{"notifications":[{"cloudPubsubTopic":{"topicName":"projects/YOUR_PROJECT/topics/clarion-alerts","payloadFormat":"JSON"}}]}

​

Step 5: Connect Clarion

1. Open Clarion > Integrations > Google Workspace
2. Select which alert severities to ingest
3. Click Connect — this creates the integration
4. Go to the Monitors tab and add a monitor — this generates the webhook URL
5. Copy the webhook URL — you’ll need it for the next step

​

Step 6: Create a Pub/Sub Push Subscription

1. Go to Pub/Sub > Subscriptions > Create Subscription
2. Configure:
   • Subscription ID: e.g. clarion-alerts-push
   • Topic: select the topic from Step 1
   • Delivery type: Push
   • Endpoint URL: paste the webhook URL from Clarion
   • Enable authentication: toggle on
     • Service account: select the service account from Part 1
     • Audience: leave blank (defaults to the endpoint URL, which matches Clarion’s OIDC audience)
   • Message retention: 7 days (default)
   • Acknowledgement deadline: 30 seconds
3. Click Create

​

Step 7: Verify

• Check Admin Console > Security > Alert Center for existing alerts
• Verify alerts appear in Clarion — Pub/Sub will retry delivery if the webhook returns a non-2xx status
• Most security alerts (suspicious login, leaked password, phishing) are on by default. Custom alerts (DLP violations, activity rules) require additional rule configuration in the Admin Console.

​

Part 3: Admin SDK Agent Tools (Optional)

​

Step 1: Add Admin SDK and Gmail Scopes

1. Go to Google Workspace Admin Console as a Super Admin
2. Navigate to Security > Access and data control > API controls
3. Click Manage Domain Wide Delegation
4. Find the existing entry for your service account’s Client ID (added in Part 2, Step 2)
5. Click Edit and update the OAuth Scopes to include all six (comma-separated, no spaces):

https://www.googleapis.com/auth/apps.alerts,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.modify

6. Click Authorize

​

Step 2: Upload Credentials in Clarion

1. In the Clarion integration settings, go to the Agent Tools (Admin SDK) tab:
   • Enter the Super Admin Email (e.g. admin@yourdomain.com) — this is the account the service account will impersonate
   • Upload the JSON key file from Part 1, Step 3
2. Click Save

​

Step 3: Verify

• When an alert comes in and triggers an agent, the agent should be able to use Google Workspace tools (user lookup, suspend, etc.)
• You can test by ensuring the service account can impersonate the admin: if credentials are wrong, agent tool calls will fail with auth errors

​

Troubleshooting

​

Request had insufficient authentication scopes

​

unauthorized_client: Client is unauthorized to retrieve access tokens using this method

1. Cloud Console: Service account has domain-wide delegation enabled (Advanced settings)
2. Admin Console: Client ID is authorized with the required scopes (Security > API controls > Domain-wide Delegation)

​

Service account key creation is disabled

​

Google Workspace Alert Center API has not been used in project ... before or it is disabled

​

Summary Checklist