Google SecOps SOAR Integration Guide

Overview

The Google SecOps SOAR integration allows your NINA workflows to connect with Google Security Operations (Google SecOps) to manage SOAR automation infrastructure — the building blocks that drive playbooks, automation actions, and analyst workspaces. This integration targets the Google SecOps SOAR Automation API and the Legacy SOAR API, providing programmatic control over environments, dynamic parameters, email and request templates, SOAR domains, SOAR networks, identity provider mapping groups, permission groups, users, and personal workdesk items.

This connector is complementary to the chronicle-cases and chronicle-instances connectors. Where chronicle-cases manages the SOC case lifecycle (cases, alerts, tasks, SLAs) and chronicle-instances manages platform-level configuration (rules, feeds, ingestion), chronicle-soar manages the automation layer: the environments where playbooks run, the parameters they consume, the templates they send, and the network/domain topology they operate within.

Capabilities

This integration provides access to 16 resources with 74 unique operations covering:

Category	Resources
Automation Parameters	Dynamic Parameters, Form Dynamic Parameters
Automation Environments	SOAR Environments, Environment Groups
Messaging Templates	Email Templates, Request Templates
Network & Domain Topology	SOAR Domains, SOAR Networks
Identity & Access (Legacy SOAR)	IDP Mapping Groups, Permission Groups
User Management (Legacy SOAR)	Legacy SOAR Users
Personal Workspace (Legacy SOAR)	User Attachments, User Notifications, Workdesk Contacts, Workdesk Links, Workdesk Notes

API Versions

The connector targets the most stable version available per resource:

API Version	Usage
`v1`	All SOAR Automation resources (dynamicParameters, emailTemplates, environmentGroups, environments, formDynamicParameters, requestTemplates, soarDomains, soarNetworks) and legacy user settings that are promoted to v1 (legacySoarUsers locale/notification settings, legacySoarUsers/attachments, legacySoarUsers/userNotifications, legacySoarUsers/workdesk*)
`v1alpha`	Legacy SOAR resources that remain in preview (legacySoarIdpMappingGroups, legacySoarPermissionGroups, legacySoarUsers CRUD)

Note: The Google SecOps API exposes the same logical operations across v1, v1alpha, and v1beta. This connector always uses a single stable version per operation. The same service account credentials work across all versions.

Credential Configuration

Authentication Method

Google SecOps SOAR uses Google Service Account (OAuth2 service-account flow). The integration authenticates by exchanging a service account JSON key for a short-lived Google access token, which is refreshed automatically — no user interaction or browser redirect is required.

Field	Description	Required
`serviceAccountJson`	Full content of the Google service account JSON key file — paste the entire JSON object	Yes
`region`	Google SecOps API region prefix that matches your instance deployment (e.g. `us`, `eu`)	Yes
`project`	GCP project ID that owns the Google SecOps instance (e.g. `my-project-123`)	Yes
`location`	GCP location string inserted into the resource path (e.g. `us`, `eu`, `europe-west2`)	Yes
`instance`	Google SecOps instance UUID (e.g. `fca7f167-b9d1-43b1-9d03-0257d31dcb63`)	Yes

How Authentication Works

You paste the service account JSON key when creating a credential in NINA.
On each API call the connector uses the golang.org/x/oauth2/google library to exchange the service account private key for a short-lived Google access token with the scope https://www.googleapis.com/auth/cloud-platform.
The token is sent as a Bearer header on every Google SecOps SOAR API request.
Google access tokens expire after 1 hour. The OAuth2 library renews tokens automatically in the background.
No redirect URLs, browser flows, or user-level OAuth consent screens are involved.

Google SecOps API Regions

Select the region value that matches where your Google SecOps instance is deployed. This value determines the Google SecOps API base URL https://{region}-chronicle.googleapis.com.

`region` value	Label	Google SecOps API base URL
`us`	United States	`https://us-chronicle.googleapis.com`
`eu`	Europe	`https://eu-chronicle.googleapis.com`
`asia-southeast1`	Asia Pacific — Singapore	`https://asia-southeast1-chronicle.googleapis.com`
`asia-south1`	Asia Pacific — India	`https://asia-south1-chronicle.googleapis.com`
`northamerica-northeast2`	Canada — Montreal	`https://northamerica-northeast2-chronicle.googleapis.com`
`me-west1`	Middle East	`https://me-west1-chronicle.googleapis.com`

region vs location: region controls which API hostname is used. location is inserted into every resource path: /v1/projects/{project}/locations/{location}/instances/{instance}. For most deployments both have the same value (e.g. both eu). For some multi-region GCP deployments the location may be a full GCP region name such as europe-west2. Confirm the exact location with your Google SecOps administrator or by inspecting the instance resource name in Google SecOps UI → Settings → Instance.

Required IAM Permissions

Google SecOps SOAR uses Google Cloud IAM roles to control access. Grant the role at the GCP project level on the project that owns the Google SecOps instance.

Use case	Required IAM role
Read-only (list/get environments, templates, domains, networks, users, IDP groups)	`roles/chronicle.viewer`
Read + write (create/update/delete environments, templates, domains, networks, IDP groups)	`roles/chronicle.editor`
Full access including destructive operations (deleteAll networks, batch-delete templates, delete users)	`roles/chronicle.editor`

Important: roles/chronicle.editor gives the service account write access to all Google SecOps resources in the project, including Cases and Instances connectors. Apply the principle of least privilege: use roles/chronicle.viewer for read-only automation workflows (monitoring, reporting, syncing environments) and roles/chronicle.editor only when write access is required.

Google SecOps-specific IAM roles and their fine-grained permissions are documented at: https://cloud.google.com/iam/docs/understanding-roles#chronicle-roles

Shared Credential with Other Google SecOps Connectors

The chronicle-soar, chronicle-cases, and chronicle-instances connectors all use identical credential fields (serviceAccountJson, region, project, location, instance) and the same IAM role model. A single service account with the appropriate Google SecOps IAM role can be used as the credential for all three connectors simultaneously — you do not need separate service accounts.

How to Obtain a Service Account Key

Step 1 — Identify or create the service account

Go to Google Cloud Console and select the GCP project that owns the Google SecOps instance.
Navigate to IAM & Admin > Service Accounts.
Either select an existing service account dedicated to NINA automation, or click Create Service Account:
- Name: A descriptive name, e.g. nina-chronicle-soar.
- Description: e.g. "Service account for NINA Google SecOps SOAR connector".
Click Create and Continue.

Step 2 — Grant the required IAM role

In IAM & Admin > IAM, click Grant Access.
Enter the service account email (e.g. [email protected]).
In the Role picker, search for and select one of:
- Google SecOps Viewer (roles/chronicle.viewer) — for read-only access.
- Google SecOps Editor (roles/chronicle.editor) — for full read/write access.
Click Save.

Step 3 — Create a JSON key

In IAM & Admin > Service Accounts, click the service account you configured.
Open the Keys tab.
Click Add Key > Create new key.
Select JSON and click Create.
The key file downloads automatically to your computer.
Store the key file securely. Anyone who possesses this file can authenticate as the service account. Do not commit it to source control, print it, or log its contents.

The JSON key file has the following structure:

{
  "type": "service_account",
  "project_id": "your-gcp-project-id",
  "private_key_id": "abc123...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
  "client_email": "[email protected]",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/..."
}

Step 4 — Locate your Google SecOps instance values

You need four values from your Google SecOps deployment: project, location, instance, and region.

Value	Where to find it
`project`	The GCP project ID shown in the Google Cloud Console project selector
`location`	Visible in the Google SecOps instance resource name: `projects/{project}/locations/{location}/instances/{instance}` — check Google SecOps UI → Settings → Instance
`instance`	The UUID portion of the instance resource name (same path as above)
`region`	The Google SecOps API region — matches the prefix of the Google SecOps UI URL (e.g. if the UI is at `eu-chronicle.security.google.com`, then `region=eu`)

Creating a Google SecOps SOAR Credential in NINA

Navigate to the Credentials section in NINA.
Click Add New Credential.
Select Google SecOps SOAR as the Integration Service.
Fill in the credential fields:
- Service Account JSON: Paste the entire contents of the downloaded .json key file.
- Region: Select your Google SecOps API region from the dropdown (e.g. eu).
- Project: Enter your GCP project ID (e.g. my-project-123).
- Location: Enter the GCP location string (e.g. eu or europe-west2).
- Instance: Enter the Google SecOps instance UUID.
Click Test Connection to verify the credentials.
Click Save to store the credential securely.

Rate Limits and Quotas

Behaviour	Detail
Rate-limit response	HTTP 429 — connector retries automatically
Retry policy	Up to 3 retries with exponential back-off: 1 s, 2 s, 4 s
Retry-After header	Honoured when present in the 429 response
Request timeout	90 seconds per request
Quota type	Google SecOps API quotas are per-project and per-method; contact Google Cloud support to increase limits

Supported Operations

Resources overview

Resource	Operations	Description
dynamicParameters	7	SOAR dynamic parameters used in playbooks and automation actions
emailTemplates	8	Email templates sent by automation actions
environmentGroups	5	Groups that organise SOAR environments
environments	6	SOAR execution environments for automation
formDynamicParameters	3	Dynamic parameters associated with SOAR forms
requestTemplates	5	Request templates used in automation actions
soarDomains	7	SOAR domain definitions
soarNetworks	8	SOAR network definitions
legacySoarIdpMappingGroups	8	Identity provider mapping groups for Legacy SOAR
legacySoarPermissionGroups	1	Legacy SOAR permission groups (read-only)
legacySoarUsers	7	Legacy SOAR user accounts and their settings
legacySoarUserAttachments	5	File attachments for Legacy SOAR users
legacySoarUserNotifications	4	In-app notifications for Legacy SOAR users
legacySoarWorkdeskContacts	5	Workdesk contacts for Legacy SOAR users
legacySoarWorkdeskLinks	5	Quick-access links on the SOAR workdesk
legacySoarWorkdeskNotes	5	Personal notes on the SOAR workdesk

Operation Details

dynamicParameters

Manage SOAR dynamic parameters — named key/value pairs injected into playbooks and automation actions at runtime. Dynamic parameters allow you to centralise configuration values (API endpoints, thresholds, environment-specific identifiers) so they can be changed in one place without editing each playbook individually.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new dynamic parameter
`delete`	DELETE	Delete a dynamic parameter by name
`get`	GET	Retrieve a single dynamic parameter
`list`	GET	List all dynamic parameters
`update`	PATCH	Update an existing dynamic parameter
`export`	POST	Export dynamic parameters to a portable format
`import`	POST	Import dynamic parameters from a portable format

create

Creates a new dynamic parameter.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Parameter name (used as the key in playbooks).
`value`	string	No	Parameter value.
`description`	string	No	Human-readable description of the parameter's purpose.

Example:

{
  "name": "siem_api_endpoint",
  "value": "https://siem.example.com/api/v2",
  "description": "Base URL for the external SIEM API used in enrichment playbooks"
}

delete

Deletes a dynamic parameter. This operation is destructive and cannot be undone. Any playbook or action that references the deleted parameter by name will fail at runtime.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the parameter to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167.../dynamicParameters/siem_api_endpoint"
}

get

Retrieves a single dynamic parameter by its resource name.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the parameter.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167.../dynamicParameters/siem_api_endpoint"
}

list

Lists all dynamic parameters in the instance. Supports pagination.

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results to return.
`pageToken`	string	No	Pagination token from a previous response to retrieve the next page.
`filter`	string	No	Filter expression to narrow results.

Example:

{
  "pageSize": 50
}

update

Updates an existing dynamic parameter. Use updateMask to update only specific fields.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the parameter to update.
`value`	string	No	New parameter value.
`description`	string	No	New description.
`updateMask`	string	No	Comma-separated list of field paths to update (e.g. `value,description`). If omitted, all provided fields are updated.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167.../dynamicParameters/siem_api_endpoint",
  "value": "https://siem.example.com/api/v3",
  "updateMask": "value"
}

export

Exports all dynamic parameters to a portable format for backup or migration.

Parameters: None.

Example:

{}

import

Imports dynamic parameters from a previously exported portable format.

Parameters:

Name	Type	Required	Description
`content`	string	No	Serialised parameters content to import (the format returned by `export`).

Example:

{
  "content": "<exported content string>"
}

emailTemplates

Manage email templates used by Google SecOps SOAR automation actions. Templates support placeholders that are substituted at runtime with case or alert data.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new email template
`delete`	DELETE	Delete an email template
`batchDelete`	DELETE	Delete multiple email templates in one request
`get`	GET	Retrieve a single email template
`list`	GET	List all email templates
`update`	PATCH	Update an email template
`export`	POST	Export email templates
`import`	POST	Import email templates

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Human-readable template name displayed in the SOAR UI.
`subject`	string	No	Email subject line. May contain `{{placeholder}}` variables.
`body`	string	No	Email body. May contain `{{placeholder}}` variables. HTML is supported.

Example:

{
  "displayName": "Incident Notification — High Severity",
  "subject": "SOAR Incident: {{case.name}} — {{alert.severity}}",
  "body": "<p>Case <strong>{{case.id}}</strong> requires immediate attention.</p>"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the email template to delete.

batchDelete

Deletes multiple email templates in a single API call. More efficient than calling delete repeatedly.

Parameters:

Name	Type	Required	Description
`names`	array	Yes	Array of fully-qualified resource names to delete.

Example:

{
  "names": [
    "projects/my-project/locations/eu/instances/fca7f167.../emailTemplates/template-1",
    "projects/my-project/locations/eu/instances/fca7f167.../emailTemplates/template-2"
  ]
}

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the email template.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results to return.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the template to update.
`displayName`	string	No	New display name.
`subject`	string	No	New subject line.
`body`	string	No	New body.
`updateMask`	string	No	Comma-separated field paths to update.

export

Exports all email templates for backup or migration.

Parameters: None.

import

Parameters:

Name	Type	Required	Description
`content`	string	No	Serialised templates content returned by `export`.

environmentGroups

Manage environment groups — logical containers that group one or more SOAR environments. Environment groups are used in playbook routing to target actions at a specific group of environments rather than a single one.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new environment group
`delete`	DELETE	Delete an environment group
`get`	GET	Retrieve a single environment group
`list`	GET	List all environment groups
`update`	PATCH	Update an environment group

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Environment group display name.
`description`	string	No	Description of the group's purpose.

Example:

{
  "displayName": "Production Environments",
  "description": "All production SOAR environments — actions here affect live cases"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the environment group.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the environment group.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`description`	string	No	New description.
`updateMask`	string	No	Comma-separated field paths to update.

environments

Manage SOAR environments — isolated execution contexts where Google SecOps SOAR automation agents run. Each environment has its own set of integration configurations, credentials, and agent connections. Environments are the primary unit of isolation between production, staging, and development automation.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new SOAR environment
`delete`	DELETE	Delete a SOAR environment
`get`	GET	Retrieve a single SOAR environment
`list`	GET	List all SOAR environments
`update`	PATCH	Update a SOAR environment
`resetWeights`	POST	Reset load-balancing weights for all environments

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Environment display name.
`description`	string	No	Description of the environment's purpose (e.g. "Production — EU region").

Example:

{
  "displayName": "Production — EU",
  "description": "Production SOAR environment for EU Google SecOps instance"
}

delete

Caution: Deleting an environment removes all its configuration, agent bindings, and integration credentials. This operation is irreversible. Ensure no active playbooks reference this environment before deleting.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the environment.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the environment.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

Example response fields of interest:

Field	Description
`name`	Fully-qualified resource name
`displayName`	Human-readable name
`description`	Environment description
`weight`	Load-balancing weight for multi-environment deployments
`retentionDuration`	Data retention period in days

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`description`	string	No	New description.
`updateMask`	string	No	Comma-separated field paths to update.

resetWeights

Resets the load-balancing weights for all SOAR environments to their default values. Use after adding or removing environments from a multi-environment deployment to restore balanced agent distribution.

Parameters: None.

Example:

{}

formDynamicParameters

Manage dynamic parameters associated with SOAR manual action forms. Form dynamic parameters populate dropdown lists and other interactive fields when an analyst responds to a manual action. The saveForm operation persists a form's current parameter values so they are available in subsequent form renders.

Operations summary

Operation	HTTP	Description
`get`	GET	Retrieve a single form dynamic parameter
`list`	GET	List all form dynamic parameters
`saveForm`	POST	Save a form with its current dynamic parameter values

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the form dynamic parameter.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

saveForm

Persists a form together with its current dynamic parameter values. This is typically called by automation to pre-populate form fields before presenting them to an analyst.

Parameters:

Name	Type	Required	Description
`formName`	string	Yes	Name of the form to save.
`values`	object	No	Map of parameter name → value to persist.

Example:

{
  "formName": "BlockIPAddressForm",
  "values": {
    "target_firewall": "fw-prod-01",
    "block_duration_hours": "24"
  }
}

requestTemplates

Manage request templates used by automation actions that make HTTP requests to external services. A request template encapsulates the HTTP method, URL pattern, headers, and body structure so playbooks can reference a template by name rather than duplicating configuration.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new request template
`delete`	DELETE	Delete a request template
`get`	GET	Retrieve a single request template
`list`	GET	List all request templates
`update`	PATCH	Update a request template

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Template display name.
`content`	string	No	Template content (URL pattern, headers, body structure).

Example:

{
  "displayName": "JIRA Create Issue",
  "content": "POST https://jira.example.com/rest/api/2/issue\nContent-Type: application/json\n\n{\"fields\":{\"summary\":\"{{case.name}}\"}}"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`content`	string	No	New content.
`updateMask`	string	No	Comma-separated field paths to update.

soarDomains

Manage SOAR domain definitions. Domains are used to organise automation resources and segment automation by functional area or business unit. Domains can also be exported/imported for backup and cross-instance migration.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new SOAR domain
`delete`	DELETE	Delete a SOAR domain
`get`	GET	Retrieve a single SOAR domain
`list`	GET	List all SOAR domains
`update`	PATCH	Update a SOAR domain
`export`	POST	Export SOAR domains
`import`	POST	Import SOAR domains

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Domain display name.
`description`	string	No	Domain description.

Example:

{
  "displayName": "Network Security",
  "description": "Automation domain for network security playbooks and actions"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`description`	string	No	New description.
`updateMask`	string	No	Comma-separated field paths to update.

export

Exports all SOAR domain definitions to a portable format. Use for backup or to seed a new Google SecOps instance.

Parameters: None.

import

Parameters:

Name	Type	Required	Description
`content`	string	No	Serialised domain content returned by `export`.

soarNetworks

Manage SOAR network definitions. SOAR networks represent IP network segments relevant to your automation. They are used in entity enrichment, alert correlation, and decision logic within playbooks (e.g. "is this IP address in a trusted internal network?").

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new SOAR network
`delete`	DELETE	Delete a single SOAR network
`deleteAll`	DELETE	Delete all SOAR networks
`get`	GET	Retrieve a single SOAR network
`list`	GET	List all SOAR networks
`update`	PATCH	Update a SOAR network
`export`	POST	Export SOAR networks
`import`	POST	Import SOAR networks

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Network display name.
`cidr`	string	No	Network CIDR range (e.g. `10.0.0.0/8`).

Example:

{
  "displayName": "Corporate Internal Network",
  "cidr": "10.0.0.0/8"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

deleteAll

Caution: Deletes every SOAR network definition in the instance. This operation is irreversible. Export networks before calling this operation if you need to restore them.

Parameters: None.

Example:

{}

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`cidr`	string	No	New CIDR range.
`updateMask`	string	No	Comma-separated field paths to update.

export

Parameters: None.

import

Parameters:

Name	Type	Required	Description
`content`	string	No	Serialised network content returned by `export`.

legacySoarIdpMappingGroups

Manage Legacy SOAR identity provider (IDP) mapping groups. IDP mapping groups map external identity provider groups (from SAML or SSO providers) to Legacy SOAR permission groups and environments. This controls what level of access users who belong to an external directory group receive when they log into Google SecOps SOAR.

API Version: These operations use v1alpha — they are in preview and may change in future Google SecOps API releases.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new IDP mapping group
`delete`	DELETE	Delete an IDP mapping group
`get`	GET	Retrieve a single IDP mapping group
`list`	GET	List all IDP mapping groups
`update`	PATCH	Update an IDP mapping group
`batchUpdate`	POST	Batch update multiple IDP mapping groups
`getExternalProviders`	GET	List available external identity providers
`updateDefaultAccessSettings`	PATCH	Update the default access settings for IDP mapping

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Mapping group display name (typically the external IdP group name or ID).

Example:

{
  "displayName": "SG-security-analysts"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

Example response fields of interest:

Field	Description
`name`	Fully-qualified resource name
`displayName`	IDP group name
`externalProviderName`	Name of the external identity provider (e.g. `SecOps`)
`permissionGroupIds`	Array of Legacy SOAR permission group IDs granted to this mapping
`socRoleIds`	Array of SOC role IDs granted
`environments`	Array of environment IDs accessible (use `["*"]` for all environments)
`groupMembers`	Array of individual member mappings with `groupMemberId` and `idpGroupId`

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`updateMask`	string	No	Comma-separated field paths to update.

batchUpdate

Updates multiple IDP mapping groups in a single API call.

Parameters:

Name	Type	Required	Description
`requests`	array	Yes	Array of individual update request objects, each containing a `name` and the fields to update.

Example:

{
  "requests": [
    {
      "name": "projects/.../legacySoarIdpMappingGroups/group-id-1",
      "displayName": "SG-security-analysts-updated"
    }
  ]
}

getExternalProviders

Returns a list of all configured external identity providers available for IDP mapping. Use this to discover the valid externalProviderName values before creating mapping groups.

Parameters: None.

Example:

{}

Example response fields of interest:

Field	Description
`providerName`	The provider name to use in `externalProviderName` when creating mapping groups
`identityProviderType`	Provider type (e.g. `SAML`, `OIDC`, `NONE`)
`autoAddUser`	Whether users are automatically created on first login
`defaultPermissionGroup`	Default permission group assigned to new users from this provider
`defaultSocRoleId`	Default SOC role assigned to new users

updateDefaultAccessSettings

Updates the default access settings applied to users from an IDP who do not match any specific mapping group.

Parameters:

Name	Type	Required	Description
`defaultRole`	string	No	Default role to assign to unmapped IDP users.

legacySoarPermissionGroups

Read Legacy SOAR permission groups. Permission groups define the set of UI permissions (which SOAR screens and actions a user can access) granted to analysts and administrators. This resource is read-only — permission groups are managed in the Google SecOps SOAR UI.

API Version: Uses v1alpha.

Operations summary

Operation	HTTP	Description
`list`	GET	List all Legacy SOAR permission groups

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

Example:

{
  "pageSize": 20
}

Example response fields of interest:

Field	Description
`id`	Permission group ID (used in IDP mapping group `permissionGroupIds`)
`permissions`	Array of permission objects with `permissionIdentifier` and `isEnabled`

legacySoarUsers

Manage Legacy SOAR user accounts and their personal settings (locale, notifications). Legacy SOAR users are distinct from Google IAM/SecOps users — they are the user records maintained within the SOAR layer itself, inherited from the legacy Siemplify platform.

API Version: User CRUD operations (delete, get, list) use v1alpha. Locale and notification setting operations use v1.

Operations summary

Operation	HTTP	Description
`delete`	DELETE	Delete a Legacy SOAR user
`get`	GET	Retrieve a single Legacy SOAR user
`list`	GET	List all Legacy SOAR users
`getLocalization`	GET	Get the localization settings for the authenticated user
`getNotificationSettings`	GET	Get the notification settings for the authenticated user
`updateLocalization`	PATCH	Update the localization settings for the authenticated user
`updateNotificationSettings`	PATCH	Update the notification settings for the authenticated user

delete

Caution: Deleting a SOAR user is irreversible. Their history (case assignments, comments, wall records) remains in the system but the user account can no longer log in.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name (e.g. `projects/.../legacySoarUsers/21`).

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

Example response fields of interest:

Field	Description
`name`	Fully-qualified resource name (contains numeric user ID)
`email`	User email address
`firstName` / `lastName`	Display name components
`loginIdentifier`	The login identity string (typically matches `email`)
`accountState`	`ACTIVE`, `INACTIVE`, or `BLOCKED`
`userType`	`EXTERNAL` (SSO/IDP) or `LOCAL`
`providerName`	Name of the identity provider that manages this user
`permissionGroups`	Array of `{ id, name }` objects for assigned permission groups
`socRoles`	Array of SOC role IDs
`environmentsJson`	JSON string listing accessible environments (`["*"]` = all)

getLocalization

Returns the locale and timezone settings for the currently authenticated service account user. Note that on some Google SecOps instances this endpoint is not available (returns HTTP 404) — this is an environment constraint, not a connector defect.

Parameters: None.

getNotificationSettings

Returns the in-app notification preferences for the currently authenticated user. As with getLocalization, this may return HTTP 404 on some instances.

Parameters: None.

updateLocalization

Parameters:

Name	Type	Required	Description
`locale`	string	No	Locale code (e.g. `en-US`, `es-ES`).
`timezone`	string	No	IANA timezone name (e.g. `Europe/Madrid`, `America/New_York`).

Example:

{
  "locale": "en-US",
  "timezone": "Europe/Madrid"
}

updateNotificationSettings

Parameters:

Name	Type	Required	Description
`emailNotifications`	boolean	No	Enable (`true`) or disable (`false`) email notifications.

legacySoarUserAttachments

Manage file attachments uploaded by Legacy SOAR users to their personal workdesk area. Attachments can be documents, images, or any file a user wants to keep accessible from the SOAR workspace.

Note: This resource returns HTTP 404 on Google SecOps instances where the Legacy SOAR workdesk feature is not configured. This is an environment constraint.

Operations summary

Operation	HTTP	Description
`delete`	DELETE	Delete a user attachment
`get`	GET	Retrieve attachment metadata
`list`	GET	List all attachments for the user
`download`	POST	Download the attachment content
`upload`	POST	Upload a new attachment

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the attachment.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

download

Downloads the binary content of a user attachment.

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the attachment to download.

upload

Uploads a new attachment file.

Parameters:

Name	Type	Required	Description
`filename`	string	Yes	File name to store the attachment under.
`content`	string	Yes	Base64-encoded file content.

Example:

{
  "filename": "runbook-v3.pdf",
  "content": "JVBERi0xLjQKJcOkw7..."
}

legacySoarUserNotifications

Manage in-app notifications for Legacy SOAR users. Notifications inform users of events such as case assignments, playbook completions, and manual action requests.

Note: This resource returns HTTP 404 on Google SecOps instances where the Legacy SOAR notification feature is not configured.

Operations summary

Operation	HTTP	Description
`get`	GET	Retrieve a single notification
`list`	GET	List all notifications for the user
`count`	POST	Count unread notifications
`markAsRead`	POST	Mark one or more notifications as read

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name of the notification.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

count

Returns the count of unread notifications for the authenticated user.

Parameters: None.

markAsRead

Marks one or more notifications as read so they no longer appear in the unread count.

Parameters:

Name	Type	Required	Description
`names`	array	Yes	Array of fully-qualified notification resource names to mark as read.

Example:

{
  "names": [
    "projects/.../legacySoarUsers/userNotifications/notif-001",
    "projects/.../legacySoarUsers/userNotifications/notif-002"
  ]
}

legacySoarWorkdeskContacts

Manage workdesk contacts — a personal address book available on the Legacy SOAR analyst workdesk. Analysts can use workdesk contacts to quickly find and contact colleagues, vendors, or stakeholders during an incident.

Note: Returns HTTP 404 on Google SecOps instances where the Legacy SOAR workdesk is not configured.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new workdesk contact
`delete`	DELETE	Delete a workdesk contact
`get`	GET	Retrieve a single workdesk contact
`list`	GET	List all workdesk contacts
`update`	PATCH	Update a workdesk contact

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Contact display name.
`email`	string	No	Contact email address.

Example:

{
  "displayName": "Network Operations Center",
  "email": "[email protected]"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`email`	string	No	New email.
`updateMask`	string	No	Comma-separated field paths to update.

legacySoarWorkdeskLinks

Manage quick-access links on the Legacy SOAR analyst workdesk. Workdesk links allow analysts to bookmark frequently used URLs (e.g. runbooks, ticketing systems, documentation portals) and access them without leaving the SOAR UI.

Note: Returns HTTP 404 on Google SecOps instances where the Legacy SOAR workdesk is not configured.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new workdesk link
`delete`	DELETE	Delete a workdesk link
`get`	GET	Retrieve a single workdesk link
`list`	GET	List all workdesk links
`update`	PATCH	Update a workdesk link

create

Parameters:

Name	Type	Required	Description
`displayName`	string	Yes	Link display name.
`url`	string	Yes	The URL the link points to.

Example:

{
  "displayName": "Incident Response Runbook",
  "url": "https://wiki.example.com/security/runbooks/incident-response"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`displayName`	string	No	New display name.
`url`	string	No	New URL.
`updateMask`	string	No	Comma-separated field paths to update.

legacySoarWorkdeskNotes

Manage personal notes on the Legacy SOAR analyst workdesk. Workdesk notes allow analysts to maintain a private scratchpad for ongoing investigations, checklists, or reminders.

Note: Returns HTTP 404 on Google SecOps instances where the Legacy SOAR workdesk is not configured.

Operations summary

Operation	HTTP	Description
`create`	POST	Create a new workdesk note
`delete`	DELETE	Delete a workdesk note
`get`	GET	Retrieve a single workdesk note
`list`	GET	List all workdesk notes
`update`	PATCH	Update a workdesk note

create

Parameters:

Name	Type	Required	Description
`title`	string	Yes	Note title.
`content`	string	No	Note content (plain text or markdown).

Example:

{
  "title": "Ongoing Investigation — Lateral Movement Campaign",
  "content": "## Key IOCs\n- 10.0.1.55\n- evil-domain.example.com\n\n## Next steps\n- Block on firewall\n- Notify IR team"
}

delete

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

get

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.

list

Parameters:

Name	Type	Required	Description
`pageSize`	number	No	Maximum number of results.
`pageToken`	string	No	Pagination token.

update

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Fully-qualified resource name.
`title`	string	No	New title.
`content`	string	No	New content.
`updateMask`	string	No	Comma-separated field paths to update.

Common Workflows

Sync SOAR environments to a CMDB

Many SOC teams maintain a CMDB (Configuration Management Database) or asset inventory. Use environments.list to pull the current SOAR environment list and push it to your CMDB.

1. environments.list { "pageSize": 100 }
2. For each environment in result.environments:
   a. Extract name, displayName, description, weight, retentionDuration
   b. Upsert record into CMDB using environment name as key
3. If result.nextPageToken is set, repeat with pageToken

Propagate dynamic parameters across instances

When you manage multiple Google SecOps instances (e.g. production and staging), use export/import to keep dynamic parameters in sync.

dynamicParameters.export {}  → obtain serialised content
(Switch credential to target instance)
dynamicParameters.import { "content": "<exported content>" }

Audit IDP group memberships

To produce a weekly access audit report:

1. legacySoarIdpMappingGroups.getExternalProviders {}
   → discover all configured identity providers
2. legacySoarIdpMappingGroups.list { "pageSize": 100 }
   → list all mapping groups with their permissionGroupIds and socRoleIds
3. legacySoarPermissionGroups.list { "pageSize": 50 }
   → resolve permission group IDs to human-readable names
4. legacySoarUsers.list { "pageSize": 200 }
   → cross-reference user accounts against mapping groups
5. Produce a CSV/report correlating user → IDP group → permission groups → environments

Provision a new SOAR deployment

When onboarding a new Google SecOps SOAR environment from scratch:

1. soarNetworks.import { "content": "<network baseline>" }
   → seed the standard corporate network list
2. soarDomains.import { "content": "<domain baseline>" }
   → seed the standard SOAR domain taxonomy
3. dynamicParameters.import { "content": "<param baseline>" }
   → seed standard automation parameters
4. emailTemplates.import { "content": "<template baseline>" }
   → seed standard notification templates
5. environments.create { "displayName": "Production", ... }
   → create the production environment
6. environmentGroups.create { "displayName": "All Environments", ... }
   → create environment groups for playbook routing

Best Practices

Use updateMask on PATCH operations. Always supply updateMask with the exact field names you intend to change. Without it, the API may reset unset fields to empty values. Example: "updateMask": "value" when only changing a dynamic parameter's value.
Paginate list calls. Never assume a single page covers all results. Always check for nextPageToken in the response and loop until it is absent or empty.
Export before destructive operations. Before calling delete, deleteAll, or batchDelete, always call the corresponding export operation and store the output. This gives you a recovery path in the absence of native backup tooling.
Apply least-privilege IAM. Use roles/chronicle.viewer for read-only workflows (auditing, monitoring, syncing to external systems). Only escalate to roles/chronicle.editor for workflows that must write, create, or delete resources.
One service account per environment tier. Use separate service accounts for production and non-production Google SecOps instances. This prevents a compromised staging credential from affecting production.
Do not hardcode instance values in playbooks. Store region, project, location, and instance values as NINA credential fields or as dynamic parameters — never hardcode them inside playbook logic.
Treat Legacy SOAR resources as best-effort. The legacySoarUsers, legacySoarUserAttachments, legacySoarUserNotifications, and legacySoarWorkdesk* resources use v1alpha or are not available on all Google SecOps deployments. Always design workflows that handle HTTP 404 gracefully by checking whether the feature is available on your specific instance before depending on it.
Rotate service account keys periodically. Google recommends rotating service account keys at least every 90 days. Create a new key, update the NINA credential, verify it works, then delete the old key. Keys can be rotated without any downtime.
Monitor for 429 rate-limit responses. The connector retries automatically up to 3 times with exponential back-off, but if your automation issues many parallel requests, consider adding deliberate pacing between bulk operations.
Name resources consistently. Use a naming convention for dynamic parameters, email templates, request templates, and domains that includes an environment prefix (e.g. prod_siem_endpoint, staging_siem_endpoint). This makes it easy to identify which resources belong to which environment tier when listing across multiple instances.

Troubleshooting

Error	Cause	Resolution
`serviceAccountJson is required`	The JSON key field was left empty or whitespace-only	Paste the entire contents of the downloaded `.json` key file into the `serviceAccountJson` field
`failed to parse service account JSON`	The JSON key is malformed or truncated	Re-download the key from GCP Console and paste it again; avoid line-ending conversion issues
`token acquisition failed`	The service account does not exist, the key has been revoked, or the `token_uri` is unreachable	Verify the service account is active in GCP Console; check that the key has not been deleted from the Keys tab
HTTP 403 `PERMISSION_DENIED`	The service account lacks the required Google SecOps IAM role	Grant `roles/chronicle.viewer` (read) or `roles/chronicle.editor` (write) at the project level
HTTP 404 on Legacy SOAR resources	The Legacy SOAR workdesk or user settings feature is not enabled on this Google SecOps instance	These endpoints are optional; design your workflow to skip gracefully when a 404 is returned
HTTP 404 on SOAR Automation resources	Incorrect `project`, `location`, or `instance` values	Verify all four credential fields match the exact values shown in Google SecOps UI → Settings → Instance
HTTP 429 `RESOURCE_EXHAUSTED`	Google SecOps API rate limit reached	The connector retries automatically; if sustained, reduce parallelism in your workflow
`region is required`	The `region` field was left blank	Select a valid region from the dropdown (e.g. `eu`, `us`)
`instance is required`	The `instance` field was left blank	Enter the Google SecOps instance UUID from Google SecOps UI → Settings → Instance
`location is required`	The `location` field was left blank	Enter the GCP location string; for most EU deployments this is `eu`
Empty `{}` response body on `list`	The resource collection is empty (no items created yet)	This is normal for newly provisioned instances; create items before listing them

Verifying credentials manually

Use the following curl snippet to verify that your service account JSON key can obtain a valid Google access token and reach the Google SecOps SOAR API:

# 1. Obtain an access token using the service account key
ACCESS_TOKEN=$(python3 -c "
import google.oauth2.service_account as sa
import google.auth.transport.requests as tr
creds = sa.Credentials.from_service_account_file(
    'sa-key.json',
    scopes=['https://www.googleapis.com/auth/cloud-platform']
)
req = tr.Request()
creds.refresh(req)
print(creds.token)
")

# 2. List SOAR environments (lightweight read-only call)
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://${REGION}-chronicle.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/instances/${INSTANCE}/environments?pageSize=1"

Replace REGION, PROJECT, LOCATION, and INSTANCE with your actual values. A successful response returns either an environments array or an empty {} object. A 403 response means the IAM role is not yet applied.

Running the integration tests

CHRONICLE_SERVICE_ACCOUNT_JSON="$(cat sa-key.json)" \
CHRONICLE_REGION=eu \
CHRONICLE_PROJECT=my-gcp-project \
CHRONICLE_LOCATION=eu \
CHRONICLE_INSTANCE=fca7f167-b9d1-43b1-9d03-0257d31dcb63 \
go test -v -count=1 -timeout 120s ./internal/integrations/chronicle-soar/...

Generating an evidence report

CHRONICLE_SERVICE_ACCOUNT_JSON="$(cat sa-key.json)" \
CHRONICLE_REGION=eu \
CHRONICLE_PROJECT=my-gcp-project \
CHRONICLE_LOCATION=eu \
CHRONICLE_INSTANCE=fca7f167-b9d1-43b1-9d03-0257d31dcb63 \
./scripts/generate-evidence.sh chronicle-soar

The report is written to evidence/chronicle-soar/<date>-chronicle-soar-report.md.

Support

For issues with this integration, contact support with the following information:

The resource and operation you were calling (e.g. environments.list)
The Google SecOps API region and GCP project (never share the private key or token)
The full error message returned
Whether the issue reproduces consistently or intermittently
The Google SecOps instance ID (UUID only — do not share the full service account JSON)

Google SecOps SOAR API reference:

SOAR Automation API: https://cloud.google.com/chronicle/docs/reference/rest/v1/projects.locations.instances.environments
Legacy SOAR API: https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacySoarUsers
Google SecOps IAM roles: https://cloud.google.com/iam/docs/understanding-roles#chronicle-roles
Service account key management: https://cloud.google.com/iam/docs/creating-managing-service-account-keys

Updated: 2026-07-07

Overview​

Capabilities​

API Versions​

Credential Configuration​

Authentication Method​

How Authentication Works​

Google SecOps API Regions​

Required IAM Permissions​

Shared Credential with Other Google SecOps Connectors​

How to Obtain a Service Account Key​

Step 1 — Identify or create the service account​

Step 2 — Grant the required IAM role​

Step 3 — Create a JSON key​

Step 4 — Locate your Google SecOps instance values​

Creating a Google SecOps SOAR Credential in NINA​

Rate Limits and Quotas​

Supported Operations​

Resources overview​

Operation Details​

dynamicParameters​

Operations summary​

create​

delete​

get​

list​

update​

export​

import​

emailTemplates​

Operations summary​

create​

delete​

batchDelete​

get​

list​

update​

export​

import​

environmentGroups​

Operations summary​

create​

delete​

get​

list​

update​

environments​

Operations summary​

create​

delete​

get​

list​

update​

resetWeights​

formDynamicParameters​

Operations summary​

get​

list​

saveForm​

requestTemplates​

Operations summary​

create​

delete​

get​

list​

update​

soarDomains​

Operations summary​

create​

delete​

get​

list​

update​

export​

import​

soarNetworks​

Operations summary​

create​

delete​

deleteAll​

get​

Overview

Capabilities

API Versions

Credential Configuration

Authentication Method

How Authentication Works

Google SecOps API Regions

Required IAM Permissions

Shared Credential with Other Google SecOps Connectors

How to Obtain a Service Account Key

Step 1 — Identify or create the service account

Step 2 — Grant the required IAM role

Step 3 — Create a JSON key

Step 4 — Locate your Google SecOps instance values

Creating a Google SecOps SOAR Credential in NINA

Rate Limits and Quotas

Supported Operations

Resources overview

Operation Details

dynamicParameters

Operations summary

create

delete

get

list

update

export

import

emailTemplates

Operations summary

create

delete

batchDelete

get

list

update

export

import

environmentGroups

Operations summary

create

delete

get

list

update

environments

Operations summary

create

delete

get

list

update

resetWeights

formDynamicParameters

Operations summary

get

list

saveForm

requestTemplates

Operations summary

create

delete

get

list

update

soarDomains

Operations summary

create

delete

get

list

update

export

import

soarNetworks

Operations summary

create

delete

deleteAll

get