Skip to main content

​
Pre-requisites

  • User must have a valid Chronicle domain (e.g.,https://yourdomain.backstory.chronicle.security).
    It is mandatory to share the Chronicle instance URL to AirMDR.
    • If Chronicle is integrated with **Google Cloud IAM: **Visit https://chronicle.security
    • You may be redirected to your instance based on your organization’s identity.
    If it says something like “you do not have access”, you’re not assigned to the Chronicle environment yet.
  • Ensure proper user access:
    • Chronicle Admins
    • Analysts (Read-only or Threat Hunting)
    • API users​

​
Generate a JSON key file for authentication

1

Create Service Account JSON for Chronicle

  1. Go to Google Cloud Console.
  2. In the top menu bar, click the project selector dropdown.
  3. Select the Chronicle project (or create a new one if needed).
2

Enable the Chronicle API (if not already enabled)

  1. Navigate to “APIs & Services” > “Library”.
  2. Search for “Chronicle API”.
  3. Click Enable if it’s not already.
3

Create a New Service Account

A service account is required for the AirMDR agent to ingest data from Google WorkspaceThis account is meant for non-human applications, allowing it to access resources in GW via the Admin SDK API we enabled earlier.
This is required to access Google Workspace APIs like Admin SDK API and Google Workspace Alert Center API.
  1. Navigate to IAM & Admin > Service Accounts.
    or
    Go to Google Cloud Console → APIs & Services → Credentials → + Create credentials → Service account.
  2. Click “Create Service Account”.
  3. Provide:
    • Service account name: airmdr-agent
    • Service account ID: airmdr-agent
    • Service account Description: Describe what this service account will do
  4. Click Create and Continue.
4

Assign Roles

  1. In the Grant this service account access to project step:
    • Add Role:
      • For Chronicle, use:
        • Chronicle API Reader or
        • Chronicle API Admin (depending on needs).
    • If these roles are not available, use:
      • Project > Viewer or
      • Security Center > Security Admin (if applicable).
  2. Click Continue, then Done.
5

Generate JSON Key

  1. In the Service Accounts list, click the email ID of the account you just created.
  2. Go to the “Keys” tab.
  3. Click “Add Key” > “Create new key”.
  4. Choose JSON format.
  5. Click Create.
    The JSON file will download automatically. 🔐 Store this securely. It includes sensitive credentials.
    After successful configuration, we will now have a service account named airmdr-agent, a JSON file with the necessary credentials for this service account saved to your host.
    Keep the JSON file safe. If compromised, revoke and regenerate. Always rotate keys periodically for security best practices.

​
Configure Chronicle with AirMDR

The requirements to configure Google Security Operations (Chronicle) with AirMDR are
  • If you’re using a Service Account JSON for Chronicle access:
    1. Go to: https://console.cloud.google.com/
    2. Use the project selector at the top.
    3. Select the project where the Chronicle-related service account was created.
    4. The Project ID is shown in:
      • The top blue header bar
      • Or under IAM & Admin > Settings
  • Google provides your organization with a Chronicle instance URL. (Refer Prerequisites)
  • While the service account JSON doesn’t directly list the region, the API call targets or ingestion endpoints you use might include it: Example endpoint: This means your ingestion is tied to asia-south1. 
    https://asia-south1-ingest.backstory.googleapis.com/v1/unstructuredlogentries:batchCreate
    Region CodeGeographic LocationCity / Country
    us-central1United States (Central)Iowa
    us-east1United States (East)South Carolina
    us-east4United States (East)Northern Virginia
    us-west1United States (West)Oregon
    us-west2United States (West)Los Angeles
    us-west3United States (West)Salt Lake City
    us-west4United States (West)Las Vegas
    northamerica-northeast1North America (Northeast)Montréal, Canada
    southamerica-east1South AmericaSão Paulo, Brazil
    europe-west1Europe (West)Belgium
    europe-west2Europe (West)London, UK
    europe-west3Europe (West)Frankfurt, Germany
    europe-west4Europe (West)Netherlands
    europe-west6Europe (West)Zurich, Switzerland
    europe-central2Europe (Central)Warsaw, Poland
    asia-east1Asia (East)Taiwan
    asia-east2Asia (East)Hong Kong
    asia-northeast1Asia (Northeast)Tokyo, Japan
    asia-northeast2Asia (Northeast)Osaka, Japan
    asia-northeast3Asia (Northeast)Seoul, South Korea
    asia-south1Asia (South)Mumbai, India
    asia-south2Asia (South)Delhi, India
    asia-southeast1Asia (Southeast)Singapore
    asia-southeast2Asia (Southeast)Jakarta, Indonesia
    australia-southeast1AustraliaSydney
    australia-southeast2AustraliaMelbourne
    me-west1Middle EastTel Aviv, Israel
    me-central1Middle EastDoha, Qatar
    africa-south1AfricaJohannesburg, South Africa
The JSON key file generated for authentication with the necessary credentials for this service account saved to your host.
Share the Chronicle instance URL, Google Cloud Project ID, Google Cloud region code, and JSON file with the necessary credentials for this service account saved to your host securely to AirMDR.
(or)
Self Configure JSON key file in the AirMDR Integrations Dashboard.

​
Skills provided by Integration

Skill IDPurpose
Google Chronicle Search LogsSearches logs in Google Chronicle using UDM search query language. This skill allows security analysts to query and analyze log data to investigate security incidents.
Google Chronicle List AlertsLists alerts from Google Chronicle based on specified filters. This skill allows security analysts to retrieve alerts for specific entities, time ranges, and other criteria.
To view the details of Input Parameters and Output for the respective skills

​
Evaluate Google Chronicle JSON

1

Set Required Variables


# Replace with the path to your Chronicle service account key file
KEY_FILE="path/to/your-service-account.json"

# Chronicle OAuth2 token endpoint
TOKEN_URI="https://oauth2.googleapis.com/token"

# Required scope for Chronicle API
SCOPE="https://www.googleapis.com/auth/chronicle-backstory"
2

Get an Access Token using the JSON Key

ACCESS_TOKEN=$(curl -s -X POST "$TOKEN_URI" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "type": "service_account",
  "client_email": "$(jq -r .client_email $KEY_FILE)",
  "private_key": "$(jq -r .private_key $KEY_FILE)",
  "token_uri": "$TOKEN_URI",
  "scope": "$SCOPE"
}
EOF
 | jq -r '.access_token')
3

Use the Token in a Chronicle API Request

curl -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://backstory.googleapis.com/v1/entities/assets"
Response If everything is set up correctly, you will receive a valid JSON response. If not, you might see:
  • 401 Unauthorized → token is invalid or expired.
  • 403 Forbidden → service account lacks permissions.
  • 404 Not Found → incorrect endpoint or API not enabled.

​
Configure Google Chronicle JSON key file in the AirMDR Integrations Dashboard

  1. Navigate to AirMDR, provide the credentials and click Login. Datadog11 Pn
  2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations. Datadog9 Pn
  3. Use the search option, enter the keyword “Google Security Operations (Chronicle)”, select the Connections tab, and click Add New Connection. Google Chronicle3 Pn
  4. Enter an unique name to the Instance (e.g., your org name-Google Chronicle) to easily identify the user connection by AirMDR.
  5. Enter the generated JSON key file in the Authentication Details field params, and click Create.
Google Chronicle4 Pn