Verify firewall configuration for the Chronicle API

Supported in:

This document describes the network firewall and proxy rules required for clients, collectors, and integrations to communicate with the Google Security Operations Chronicle API.

Verify firewall and proxy configuration

If you use firewalls or authenticated proxies between your environment and the internet, configure rules to allow outbound HTTPS and Transport Layer Security (TLS) connections on TCP port 443. Allow access to the following Google Cloud hosts:

  • Chronicle API endpoints: Allow access to the locational endpoint (<var>REGION</var>-chronicle.googleapis.com) or regional endpoint (chronicle.<var>REGION</var>.rep.googleapis.com) that corresponds to your Google SecOps instance location. Your Chronicle API endpoint serves all platform capabilities, including log and event ingestion, Unified Data Model (UDM) search, Detection Engine rules and retrohunts, built-in dashboards, entity risk and User and Entity Behavior Analytics (UEBA), reference lists, data tables, feeds, and SOAR case management.
  • Google authentication and API endpoints: Allow access to oauth2.googleapis.com, www.googleapis.com, and accounts.google.com (plus sts.googleapis.com and iamcredentials.googleapis.com if you use Workload Identity Federation or service account impersonation). Client libraries, collectors, and integrations require these endpoints to authenticate, exchange credentials, verify certificates, and refresh OAuth 2.0 tokens.
Connection type Destination Port Purpose
TCP (HTTPS) <var>REGION</var>-chronicle.googleapis.com 443 Locational Chronicle API endpoint for your instance (for example, us-chronicle.googleapis.com or europe-west2-chronicle.googleapis.com). For all supported locations, see Service endpoint.
TCP (HTTPS) chronicle.<var>REGION</var>.rep.googleapis.com 443 Regional or multi-regional Chronicle API endpoint (rep) with in-region TLS termination (for example, chronicle.us.rep.googleapis.com). For supported regions, see Regional service endpoints.
TCP (HTTPS) chronicle.googleapis.com 443 Global Chronicle API service endpoint.
TCP (HTTPS) oauth2.googleapis.com 443 OAuth 2.0 token acquisition and refresh.
TCP (HTTPS) www.googleapis.com 443 Google API authentication, token verification certificates, and API discovery.
TCP (HTTPS) accounts.google.com 443 Google identity and service account authentication.
TCP (HTTPS) sts.googleapis.com 443 Token exchange when using Workload Identity Federation or Workforce Identity Federation (if applicable).
TCP (HTTPS) iamcredentials.googleapis.com 443 Short-lived credential generation when using service account impersonation (if applicable).

Google IP address ranges and private connectivity

Google APIs and authentication services use dynamically allocated IP addresses that change frequently. Don't configure firewall rules with hardcoded IP addresses obtained from one-time DNS lookups.

Depending on your network architecture, use one of the following approaches:

  • Public internet egress (dynamic IP ranges): If your firewall doesn't support domain-based rules and requires IP Classless Inter-Domain Routing (CIDR) blocks, configure automated updates using published Google IP ranges (goog.json and cloud.json). For instructions and a sample Python script to calculate default domain IP ranges, see IP addresses for default domains and Obtain Google IP address ranges.
  • Private Google Access (static virtual IPs): To connect from Virtual Private Cloud virtual machines (VMs) or on-premises networks (over Cloud VPN or Cloud Interconnect) without traversing the public internet or maintaining dynamic IP lists, use Private Google Access or Private Google Access for on-premises hosts with private.googleapis.com (199.36.153.8/30) or restricted.googleapis.com (199.36.153.4/30).
  • Private Service Connect: To access Google APIs using a private internal IP address in your VPC network, use Private Service Connect endpoints for Google APIs. Regional endpoints (chronicle.<var>REGION</var>.rep.googleapis.com) aren't accessible through private.googleapis.com or restricted.googleapis.com. To connect privately to a *.rep.googleapis.com endpoint, see Access regional Google APIs through private endpoints.

Test network connectivity

To verify that your firewall or proxy allows outbound HTTPS connections and TLS handshakes to the Chronicle API and Google authentication endpoints on TCP port 443, run the connectivity checks for your operating system.

Linux or macOS

  1. Open a terminal on the host where your API client, collector, or integration runs.

  2. Test HTTPS connectivity and TLS negotiation on port 443 to your Chronicle API endpoint and the required authentication hosts using curl:

    curl -Iv https://<var>REGION</var>-chronicle.googleapis.com
curl -Iv https://oauth2.googleapis.com
curl -Iv https://www.googleapis.com
curl -Iv https://accounts.google.com

    Replace <var>REGION</var> with the region prefix or multi-region name for your Google SecOps instance (for example, us, eu, or europe-west2). A successful connection completes the TLS handshake and returns an HTTP response header (such as HTTP/2 404 or HTTP/2 200).

Windows PowerShell

  1. Start Windows PowerShell with administrator privileges.

  2. Test TCP port 443 and HTTPS reachability for your Chronicle API endpoint and each required authentication host:

    Test-NetConnection <var>REGION</var>-chronicle.googleapis.com -Port 443
Invoke-WebRequest -Uri https://<var>REGION</var>-chronicle.googleapis.com -Method Head -SkipHttpErrorCheck
Invoke-WebRequest -Uri https://oauth2.googleapis.com -Method Head -SkipHttpErrorCheck
Invoke-WebRequest -Uri https://www.googleapis.com -Method Head -SkipHttpErrorCheck
Invoke-WebRequest -Uri https://accounts.google.com -Method Head -SkipHttpErrorCheck

    Replace <var>REGION</var> with the region prefix or multi-region name for your Google SecOps instance (for example, us, eu, or europe-west2). Verify that TcpTestSucceeded returns True and Invoke-WebRequest returns an HTTP StatusCode without a proxy or TLS connection error.