Stay organized with collections Save and categorize content based on your preferences.

Customer Management API

How to authenticate with the Chronicle API

This Chronicle API uses the OAuth 2.0 protocol for authentication and authorization. Your application can complete these tasks using either of the following implementations:

  • Using the Google API Client Library for your computer language.

  • Directly interfacing with the OAuth 2.0 system using HTTP.

See the reference documentation for the Google Authentication library in Python.

Google Authentication libraries are a subset of the Google API client libraries. See other language implementations.

Getting API authentication credentials

Your Chronicle representative will provide you with a Google Developer Service Account Credential to enable the API client to communicate with the API.

You also must provide the Auth Scope when initializing your API client. OAuth 2.0 uses a scope to limit an application's access to an account. When an application requests a scope, the access token issued to the application is limited to the scope granted.

Use the following scope to initialize your Google API client:

https://www.googleapis.com/auth/chronicle-backstory

Python example

The following Python example demonstrates how to use the OAuth2 credentials and HTTP client using google.oauth2 and googleapiclient.

# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.oauth2 import service_account
from googleapiclient import _auth

SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']

# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'

# Create a credential using Google Developer Service Account Credential and Chronicle API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build an HTTP client to make authorized OAuth requests.
http_client = _auth.authorized_http(credentials)

# <your code continues here>

Chronicle API Query Limits

The Chronicle API enforces limits on the volume of requests that can be made by any one customer against the Chronicle platform. If you reach or exceed the query limit, the Chronicle API server returns HTTP 429 (RESOURCE_EXHAUSTED) to the caller. When developing applications for the Chronicle API, Chronicle recommends that you enforce rate limits within your system to avoid resource exhaustion. These limits apply to all of the Chronicle APIs, including the Search, Customer Management, and Tooling APIs. The following limit for the Chronicle Customer Management API is being enforced and is measured in queries per day (QPD):

Chronicle API API Method Limit
Customer Management CreateCustomer 10 QPD

Regional Endpoints

Your API endpoint varies depending on where your customer account is provisioned:

  • European Union—https://europe-backstory.googleapis.com
  • United States—https://backstory.googleapis.com
  • Asia—https://asia-southeast1-backstory.googleapis.com

Onboarding Chronicle Customer APIs

You can onboard new Chronicle customers using the following API calls:

CreateCustomer GetCustomer GetCustomerForwarderConfigs ListCustomers SetUIState UpdateSSOConfig

CreateCustomer

Creates a customer and associates this customer with the partner. This API fully provisions a customer in Chronicle. The response includes the customer ID.

Note: CreateCustomer uses the POST method. If the POST call returns the error message "customer creation failed, creation may be retried by rerunning with the same parameters", CreateCustomer may be retried by rerunning the same request.

Request

https://backstory.googleapis.com/v1/partner/customer/createcustomer
Request Body
{
    'customer_name': 'name',
    'customer_code': 'code',
    'customer_subdomains': 'subdomain',
    'sso_config': 'byte_representation_of_sso_config'
}
Sample Request
https://backstory.googleapis.com/v1/partner/customer/createcustomer
{
    'customer_name': 'name',
    'customer_code': 'code',
    'customer_subdomains': 'subdomain',
    'sso_config': 'byte_representation_of_sso_config'
}
Sample Response
{
    "id":"a216c252-adf8-4c65-b034-bb01b0619c8d",
    "customer_id":"1GVjfYUMQ/Gjzkv2/jvz3w==",
    "customer_code":"CODE",
    "customer_name":"NAME",
    "sso_config":{
    "create_time":"2018-09-14T20:10:27.157476Z",
    "deploy_time":"2018-09-14T22:10:27.157476Z",
    "state":"DEPLOYED",
    "config":"SSO_CONFIG_DEPLOYED"
    },
    "credentials":[
    {
        "id":"7a34158e-75ba-4da8-917d-a1db53527059",
        "credential_type":"BACKSTORY_API",
        "credential":"12GVjfYUMQ+="
    },
    {
        "id":"c180fd3d-442f-4fc1-a84a-a9b394643625",
        "credential_type":"INGESTION_API",
        "credential":"13GVjfYUMQ+="
    },
    {
    "id": "f7a79c4c-3125-4110-a397-a8bdbb10887d",
    "credential_type": "BIGQUERY_API",
    "credential": "14GVjfYUMQ+="
    }
]
}

GenerateIdPMetadata

Generates new IdP metadata for a given subdomain. Customers can access Chronicle using <subdomain>.backstory.chronicle.security.

Request

https://backstory.googleapis.com/v1/partner/customer/generateidpmetadata
Sample Request
https://backstory.googleapis.com/v1/partner/customer/generateidpmetadata
{
    "customer_subdomain": "customer-subdomain"
}
Sample Response
{
    "metadata": "<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://customer-subdomain.backstory.chronicle.security/">
        <md:Extensions xmlns:alg="urn:oasis:names:tc:SAML:metadata:algsupport">
            <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512"/>
            <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha384"/>
            <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha224"/>
            <alg:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha384"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2009/xmldsig11#dsa-sha256"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <alg:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
        </md:Extensions>

        <md:SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <md:Extensions>
            <init:RequestInitiator xmlns:init="urn:oasis:names:tc:SAML:profiles:SSO:request-init" Binding="urn:oasis:names:tc:SAML:profiles:SSO:request-init" Location="https://customer-subdomain.backstory.chronicle.security/"/>
            </md:Extensions>

            <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://customer-subdomain.backstory.chronicle.security/acs"/>
        </md:SPSSODescriptor>

    </md:EntityDescriptor>"
}

GetCustomer

Retrieves the customer details, including the customer name, forwarder IDs, stored credentials, and subdomains for a given customer being managed by the calling partner.

Request

https://backstory.googleapis.com/v1/partner/customer/getcustomer?customer_code=code
Sample Request
https://backstory.googleapis.com/v1/partner/customer/getcustomer?customer_code=mycustomercode
Sample Response
{
    "id":"a216c252-adf8-4c65-b034-bb01b0619c8d",
    "customer_id":"1GVjfYUMQ/Gjzkv2/jvz3w==",
    "customer_code":"CODE",
    "customer_name":"NAME",
    "forwarders":[
    "7f675b71-e7c5-4f2a-b621-d1f0f78a0029"
    ],
    "customer_subdomains":[
    "domain1"
    ],
    "sso_config":{
    "create_time":"2018-09-14T20:10:27.157476Z",
    "deploy_time":"2018-09-14T22:10:27.157476Z",
    "state":"DEPLOYED",
    "config":"SSO_CONFIG_DEPLOYED"
    },
    "credentials":[
    {
        "id":"7a34158e-75ba-4da8-917d-a1db53527059",
        "credential_type":"BACKSTORY_API",
        "credential":"12GVjfYUMQ+="
    },
    {
        "id":"c180fd3d-442f-4fc1-a84a-a9b394643625",
        "credential_type":"INGESTION_API",
        "credential":"13GVjfYUMQ+="
    },
    {
    "id": "f7a79c4c-3125-4110-a397-a8bdbb10887d",
    "credential_type": "BIGQUERY_API",
    "credential": "14GVjfYUMQ+="
    }
]
}

GetCustomerForwarderConfigs

Retrieves the customer's Linux or Windows Forwarder configuration. It first ensures that the partner identified by the service account has authorization to access the customer's forwarder. If there is more than one Chronicle Forwarder for a specific customer, the first active Forwarder is selected and its configuration is returned.

Request

https://backstory.googleapis.com/v1/partner/customer/forwarder/getconfigs?
customer_code=code
Sample Request
https://backstory.googleapis.com/v1/partner/customer/forwarder/getconfigs?
customer_code=mycustomercode
Sample Response
{
    "id": "ID",
    "forwarder_configs": [
        {
            "platform": "UNIX",
            "config": "BASE64_REPRESENTATION_OF_CONFIG"
        },
        {
            "platform": "WINDOWS",
            "config": "BASE64_REPRESENTATION_OF_CONFIG"
        }
    ]
}

ListCustomers

Retrieves a list of the customers associated with the partner. The partner is identified when they authenticate using their service account credentials.

Request

https://backstory.googleapis.com/v1/partner/customer/listcustomers
Sample Request
https://backstory.googleapis.com/v1/partner/customer/listcustomers
Sample Response
{
   "customers":[
      {
         "id":"a216c252-adf8-4c65-b034-bb01b0619c8d",
         "customer_id":"1GVjfYUMQ/Gjzkv2/jvz3w==",
         "customer_code":"CODE",
         "customer_name":"NAME",
         "forwarders":[
            "7f675b71-e7c5-4f2a-b621-d1f0f78a0029"
         ],
         "customer_subdomains":[
            "domain1"
         ],
         "sso_config":{
            "create_time":"2018-09-14T20:10:27.157476Z",
            "deploy_time":"2018-09-14T22:10:27.157476Z",
            "state":"DEPLOYED",
            "config":"SSO_CONFIG_DEPLOYED"
         },
         "credentials":[
            {
               "id":"7a34158e-75ba-4da8-917d-a1db53527059",
               "credential_type":"BACKSTORY_API",
               "credential":"12GVjfYUMQ+="
            },
            {
               "id":"c180fd3d-442f-4fc1-a84a-a9b394643625",
               "credential_type":"INGESTION_API",
               "credential":"13GVjfYUMQ+="
            },
            {
            "id": "f7a79c4c-3125-4110-a397-a8bdbb10887d",
            "credential_type": "BIGQUERY_API",
            "credential": "14GVjfYUMQ+="
            }
        ]
      }
   ]
}

SetAuthVersion

Enables you to update the authentication version for the specified customer. Complete this step only after confirming that the end-to-end authentication for the tenant they are migrating is working correctly.

Note: SetAuthVersion uses the POST method and auth_version can only be set to AUTH_VERSION_1 or AUTH_VERSION_2.

Request

https://backstory.googleapis.com/v1/partner/customer/setauthversion
Sample Request
https://backstory.googleapis.com/v1/partner/customer/setauthversion
{
    "customer_code" : "CODE",
    "auth_version"  : "AUTH_VERSION_2"
}
Sample Response
{
    "authVersion":"AUTH_VERSION_2"
}

SetComplianceRequirements

Given a customer code and a list of compliance certifications, SetComplianceRequirements sets compliance requirements for the customer.

Request

https://backstory.googleapis.com/v1/partner/customer/setcompliancerequirements
Sample Request
https://backstory.googleapis.com/v1/partner/customer/setcompliancerequirements
{
    "customer_code" : "CODE",
    "compliance_certifications": ["COMPLIANCE_CERTIFICATION_FEDRAMP_MODERATE", "COMPLIANCE_CERTIFICATION_PCI_DSS"]
}
Sample Response
{
    "complianceCertifications": "COMPLIANCE_CERTIFICATION_FEDRAMP_MODERATE"
}

SetUIState

Enables or disables the web application of a tenant managed by a partner by updating the customer's feature flag.

Request

https://backstory.googleapis.com/v1/partner/customer/setuistate:state
Sample Request
https://backstory.googleapis.com/v1/partner/customer/setuistate:state
{
    "customer_code" : "CODE",
    "state": true
}
Sample Response
{
    "state": true
}

UpdateSSOConfig

Enables you to update the SSO Configuration for the specified customer. You can optionally add a subdomain if there are multiple subdomains for a given customer. If you call this API as part of the migration from AUTH_VERSION_1 to AUTH_VERSION_2, Google recommends setting the update_v2_only field to true.

Note: UpdateSSOConfig uses HTTP PATCH request.

Request

https://backstory.googleapis.com/v1/partner/customer/updatessoconfig
Sample Request
https://backstory.googleapis.com/v1/partner/customer/updatessoconfig
{
    "customer_code" : "CODE",
    "sso_config": "NEW_CONFIG"
    "customer_subdomain": "customer-subdomain"
    "update_v2_only": "true"

}
Sample Response
{
    "create_time":"2018-09-14T20:10:27.157476Z",
    "deploy_time":"2018-09-14T22:10:27.157476Z",
    "state":"DEPLOYED",
    "config":"SSO_CONFIG_DEPLOYED"
}