Purpose
This guide explains how to connect Google Workspace to Logsign as a Response integration, so an analyst (or an action rule) can suspend or reactivate a Workspace user directly from a Logsign Incident. This is a containment integration, not a log collection poller: it does not pull any Google Workspace logs or events into Logsign. It only runs when a method is called from Settings > Integrations > Responses.
Do not confuse this with the existing "Google G Suite integration via API" article, which documents the separate poller that ingests Google Workspace admin/login/token audit logs into Logsign for detection and reporting. That poller and this Response integration use different credentials, different Google APIs, and are configured in different places in Logsign (Data Collection versus Responses). You can run either one independently of the other.
Based on a review of the integration's Go source code, only two actions are currently implemented: suspending a user (disable_user) and reactivating a suspended user (enable_user). Both call the Admin SDK Directory API's user update endpoint with the suspended field. There is no password reset, no session/token revocation, and no Gmail-specific action in the current implementation, even though the Admin SDK exposes those capabilities. If your use case needs one of those, it is not available yet; treat any mention of them elsewhere as aspirational, not shipped.
Prerequisites
You need a Google Cloud project with billing/API access under your control, and a Google Workspace Super Admin (or an admin with domain-wide delegation authorization rights) to complete the Google-side setup in Step 1. On the Logsign side you need access to Settings > Integrations > Responses.
This integration authenticates as a service account using domain-wide delegation (a signed JWT, exchanged for an access token that impersonates a real Workspace user). It does not use OAuth consent screens, refresh tokens, or a client ID/secret pair for its own calls; that flow is used by a different Google Workspace capability (SSO login) that shares the same configuration screen but is not covered by this guide. See "Notes and Limits" below for how to tell the fields apart.
Least privilege: the only OAuth scope this integration's code requests is https://www.googleapis.com/auth/admin.directory.user. Do not authorize broader scopes (for example the full Admin SDK scope set) for this integration's use case; add only what is listed in Step 1. The account you choose to impersonate (Step 1, point 5) also needs enough Admin console privilege to modify user records; Google's own guidance does not require this to be a full Super Admin, but our own live test used a Super Admin account and a scoped custom-admin-role alternative was not verified for this guide.
Step 1: Create a service account with domain-wide delegation
- In Google Cloud Console, go to IAM & Admin > Service Accounts and create a new service account (for example
logsign-response-dwd). You do not need to grant it any Google Cloud IAM roles; it only needs the Workspace-side authorization from point 3 below. - Open the new service account, go to the Keys tab, and choose Add key > Create new key > JSON. Download the key file and keep it safe; this is the credential Logsign will store encrypted in Step 2. Google only lets you download this file once.
- Still on the service account's details page, expand Show advanced settings and copy the numeric Client ID shown under domain-wide delegation. You will need this in the next step, not the service account's email address.
In the Google Workspace Admin console (
admin.google.com), sign in as a Super Admin and go to Security > Access and data control > API controls > Manage Domain Wide Delegation, then Add new. Paste the Client ID from the previous step and, in OAuth scopes, enter exactly:https://www.googleapis.com/auth/admin.directory.userClick Authorize. This is a write scope; it is what lets the service account suspend and unsuspend users. Google's own documentation states this can take up to 24 hours to propagate, though in practice it is usually much faster.
- Decide which Workspace user this service account will impersonate for its API calls (the "Impersonate User" value in Step 2). This does not have to be a personal admin account, but it must have sufficient Admin console privilege to modify user records; using a dedicated Super Admin or delegated-admin service identity, rather than a real person's daily-use account, is recommended so the integration does not break if that person's password or 2-Step Verification changes.
- Confirm the Admin SDK API is enabled for your Google Cloud project (APIs & Services > Library > Admin SDK API > Enable). If it is not enabled, every call, including the connection test in Logsign, fails.
Two behaviors of the Directory API worth knowing before you test: based on a live verification against a real tenant, the API will not let you suspend the account being impersonated, and it will not let you suspend a Super Admin account through this method, regardless of scope. Test with an ordinary, non-admin user, not with the impersonated account or another Super Admin, or the call will fail even though your setup is otherwise correct.
Step 2: Configure the integration in Logsign
In Logsign, go to Settings > Integrations > Responses, search for Google Workspace, click Configure, then +Device.
| Field | Required | Value / Notes |
|---|---|---|
| Service Account JSON (Domain-Wide Delegation key) | Yes | Paste the entire contents of the JSON key file downloaded in Step 1, unmodified, as one block. This is not a field for the private key alone; the integration parses client_email, private_key and (optionally) token_uri out of the full JSON structure that Google generates, so pasting a partial file or just the private key breaks it. Stored encrypted by Logsign. |
| Impersonate User (Workspace Super Admin email) | Yes | The full email address of the Workspace user chosen in Step 1, point 5, for example svc-admin@yourdomain.com. This is used as the sub claim of the signed JWT; it is who the API calls run as. |
| Domain | Functionally required | Your bare Workspace domain, for example yourcompany.com. No https:// prefix, no @ sign, no trailing slash. The integration appends this to whatever username an action rule or analyst supplies, if that value does not already contain an @, to build the full primaryEmail the Directory API expects. If this field is left blank and a bare username (no @) is supplied when a method runs, the call is sent with an incomplete user key and fails. |
| Customer ID | No | Defaults to my_customer. Based on a source-code review, this field is not read anywhere in the disable_user/enable_user code path; it belongs to a separate Google Workspace identity/asset sync capability that shares this same configuration screen. Leave it at the default for a response-action-only setup. |
| SSO OAuth Client ID / SSO OAuth Client Secret | No | Based on a source-code review, neither field is used by disable_user/enable_user. They belong to a separate Google Workspace SSO login capability (a different OAuth 2.0 Web Application client, not the service account JSON above) that also shares this configuration screen. Leave both blank unless you are separately setting up Google SSO login for Logsign. |
Save the device, then use Logsign's Test action on it. The test only mints an access token for the admin.directory.user scope; it does not verify that the impersonated user can actually write to a specific target account. In practice this still catches most setup mistakes, because a missing or wrong domain-wide delegation scope authorization fails at token-minting time with the same unauthorized_client error described in Troubleshooting below.
Available Methods
Both methods are invoked either manually from an Incident's Responses panel, or automatically from an action rule (the username parameter supports "mention" formatting, so it can be bound to a field on the triggering alarm).
disable_user
Suspends a Workspace user, blocking sign-in and access to all Workspace services for that account. Registered in Logsign as a Containment action, with enable_user set as its automatic Recovery action.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| username | string | Yes | Bare username or full email address of the account to suspend. If bare, the Domain field from Step 2 is appended to build the primaryEmail Google expects. |
| expire_time | enum (30 Minutes, 1 Hour, 3 Hour, 6 Hour, 12 Hour, 1 Day, 1 Week, 1 Month, Permanent) | Shown in the form, not enforced | Based on a source-code review, this dropdown is defined in the integration's manifest but the handler code that runs disable_user does not read or act on it at all; it only reads username. Whatever value you pick, the suspension does not automatically expire or auto-reverse; it stays suspended until enable_user (or a manual unsuspend in the Admin console) is run. Do not rely on this field for a time-boxed suspension. This was not confirmed against a newer build for this guide, so re-check before depending on it. |
enable_user
Reactivates a previously suspended Workspace user. Registered in Logsign as the Recovery action for disable_user, but can also be run on its own.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| username | string | Yes | Same resolution rule as disable_user's username. |
Both methods return the same result shape: a boolean success and a msg string. On failure, the integration surfaces the raw error body returned by Google's Directory API in that message, which is useful for telling apart the causes listed in Troubleshooting below.
Notes and Limits
- Only suspend/unsuspend is implemented. There is no password reset, no session or refresh-token revocation, and no Gmail-specific method (for example message export or delegation changes) in the current code, regardless of what the Admin SDK API itself supports.
- The impersonated account and any Super Admin account cannot be suspended through this integration; this is Google Directory API behavior, not a Logsign restriction, and was confirmed against a real tenant during internal testing.
- The expire_time option on disable_user is present in the UI but not implemented in the handler code as of this writing; treat suspensions as permanent until reversed by enable_user or manually in the Admin console.
- The access token used for each call is minted fresh from a signed JWT bearer assertion valid for one hour; it is not cached or reused across calls, and there is no user-facing setting for this, it is standard behavior of the current implementation.
- Customer ID and the SSO OAuth Client ID/Secret fields appear on the same configuration screen but belong to two other Google Workspace capabilities (identity/asset sync, and SSO login) that are not part of this Response integration. They can be left at their defaults if you are only using disable_user/enable_user.
- A proxy URL field exists in the integration's configuration model for routing API calls through an HTTP proxy, but it is not exposed in the current manifest's UI form; it was not verified whether it can be set through any other path for this guide.
Troubleshooting
| Symptom / Code | Likely Cause | What to Check |
|---|---|---|
| unauthorized_client (on Test, or on any method call) | The service account's Client ID either was not authorized in Domain-Wide Delegation, was authorized with the wrong scope string, or the authorization has not finished propagating yet. This exact error text was reproduced during internal verification when the write scope was missing. | In the Admin console, confirm the Client ID under Domain Wide Delegation matches the service account's advanced-settings Client ID exactly (not its email address), and that https://www.googleapis.com/auth/admin.directory.user is listed for it verbatim. Wait a few minutes and retry; Google states propagation can take up to 24 hours. |
| 401 Unauthorized / token request failure | The pasted Service Account JSON is malformed, truncated, or is not the same JSON Google generated (for example only the private key was pasted). A significant clock skew on the Logsign server can also cause JWT validation to fail. | Re-download a fresh JSON key from the service account's Keys tab and paste the full file contents into the Service Account JSON field. Confirm the Logsign server's system clock is accurate. |
| 403 Forbidden | The Admin SDK API is not enabled in the Google Cloud project, or the call targets the impersonated account itself or a Super Admin, which Google blocks regardless of scope. | Enable the Admin SDK API in the Cloud project. Re-test disable_user against an ordinary, non-admin user account instead of the impersonated account or another admin. |
| 404 Not Found | The resolved user key (username, or username@Domain) does not match any account in the Workspace directory, most often because the Domain field was left blank or misspelled, or a bare username was supplied without an @ and no Domain was configured. | Confirm the Domain field in Step 2 is set to the bare domain with no scheme or trailing slash, and that the username supplied matches an existing user's primaryEmail or its local part. |
| Call succeeds (success: true) but the user is not suspended, or reappears active later | A downstream automation, sync job, or manual admin action in Google Workspace re-enabled the account after this integration suspended it. The API call itself succeeded and there is no automatic re-suspension. | Check the Admin console's audit log for the account around the time it reactivated to identify what re-enabled it. |
| 429 Too Many Requests | Not explicitly documented for this specific Directory API method as of this guide, but Google's Admin SDK APIs are subject to per-project and per-user quotas that can be hit under bulk or scripted use. | Space out repeated calls if you are triggering this from a high-volume action rule; retry after a short delay. |