Chronicle RBAC API
The Chronicle APIs enable customers to programmatically access their security data directly through API calls to the Chronicle platform that stores and processes the data. This is the same security data presented in the Chronicle UI through your Chronicle customer account.
This capability enables you to develop new applications or modify existing applications to retrieve and process all your security data currently stored in Chronicle.
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>
Examples (in Python) for making OAuth authenticated requests to the Chronicle API are provided for each API call referenced in this document.
Frequently asked questions
Does the API endpoint vary depending on the region?
Yes. Your API endpoint will vary depending on where your customer account is provisioned:
- Canada—
https://northamerica-northeast2-backstory.googleapis.com
- Dammam—
https://me-central2-backstory.googleapis.com
- Europe Multi-Region—
https://europe-backstory.googleapis.com
- Frankfurt—
https://europe-west3-backstory.googleapis.com
- London—
http://europe-west2-backstory.googleapis.com
- Mumbai—
http://asia-south1-backstory.googleapis.com
- Singapore—
https://asia-southeast1-backstory.googleapis.com
- Sydney—
https://australia-southeast1-backstory.googleapis.com
- Tel Aviv—
https://me-west1-backstory.googleapis.com
- Tokyo—
https://asia-northeast1-backstory.googleapis.com
- United States Multi-Region—
https://backstory.googleapis.com
- Zurich—
https://europe-west6-backstory.googleapis.com
Chronicle RBAC API Reference
Role-based access control (RBAC) enables you to tailor access to Chronicle features based on an employee's role in your organization.
This section describes the Chronicle RBAC API methods.
ListRoles
Retrieves all roles.
Request
GET https://backstory.googleapis.com/v1/roles
Parameters
None
Sample Request
https://backstory.googleapis.com/v1/roles
Response
Sample Response
{
"roles": [
{
"name": "Test",
"title": "Test role",
"description": "The test role",
"isDefault": false,
"permissions": [
{
"name": "Test",
"title": "Test permission",
"description": "The test permission",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
},
...
]
},
...
],
}
UpdateRole
Updates a role to specify whether it is the default role.
Request
PATCH https://backstory.googleapis.com/v1/roles/Administrator
Body Parameters
Parameter Name | Type | Required | Description |
isDefault | bool | Yes | Whether this role should be the default role. |
Sample Request
https://backstory.googleapis.com/v1/roles/Administrator
{
"isDefault": true
}
Response
Sample Response
{
"role": {
"name": "Test",
"title": "Test role",
"description": "The test role",
"isDefault": true,
"permissions": [
{
"name": "Test",
"title": "Test permission",
"description": "The test permission",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
},
...
]
},
...
},
}
CreateSubject
Creates a subject and assigns the given role.
Request
POST https://backstory.googleapis.com/v1/subjects
Body Parameters
Parameter Name | Type | Required | Description |
name
|
string
|
Yes | The ID of the subject to be created. |
type
|
string
|
Yes | The type of the subject, e.g., SUBJECT_TYPE_ANALYST (an analyst) or SUBJECT_TYPE_IDP_GROUP (a group). |
roles
|
string
|
Yes | The role(s) the created subject must have. |
Sample Request
https://backstory.googleapis.com/v1/subjects/
{
"name": "test@test.com",
"type": "SUBJECT_TYPE_ANALYST",
"roles": [
{
"name": "Test",
}
...
]
}
Response
Sample Response
{
"subject": {
"name": "test@test.com",
"type": "SUBJECT_TYPE_ANALYST",
"roles": [
{
"name": "Test",
"title": "Test role",
"description": "The test role",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
"isDefault": false,
"permissions": [
{
"name": "Test",
"title": "Test permission",
"description": "The test permission",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
},
...
]
},
...
]
}
}
GetSubject
Retrieves a subject.
Request
GET https://backstory.googleapis.com/v1/subjects/{subject_id}
URL Parameters
Parameter Name | Type | Required | Description |
subject_id | string | Yes | Unique identifier for the subject. |
Sample Request
https://backstory.googleapis.com/v1/subjects/test@test.com
Response
Sample Response
{
"subject": {
"name": "test@test.com",
"type": "SUBJECT_TYPE_ANALYST",
"roles": [
{
"name": "Test",
"title": "Test role",
"description": "The test role",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
"isDefault": false,
"permissions": [
{
"name": "Test",
"title": "Test permission",
"description": "The test permission",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
},
...
]
},
...
]
}
}
ListSubjects
Retrieves all subjects.
Request
GET https://backstory.googleapis.com/v1/subjects
URL Parameters
Parameter Name | Type | Required | Description |
page_size | integer | Optional | Specify the maximum number of subjects to return (range is 1 through 1,000). The default is 100. |
page_token | string | Optional | Page token received from a previous call. Use to retrieve the next page. |
Sample Request
https://backstory.googleapis.com/v1/subjects?page_size=10&page_token=abc
Response
Sample Response
{
"subjects": [
{
"name": "test@test.com",
"type": "SUBJECT_TYPE_ANALYST",
"roles": [
{
"name": "Test",
"title": "Test role",
"description": "The test role",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
"isDefault": false,
"permissions": [
{
"name": "Test",
"title": "Test permission",
"description": "The test permission",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
},
...
]
},
...
]
}
….
],
"nextPageToken": "NEXT_PAGE_TOKEN",
}
UpdateSubject
Updates the role of the specified subject.
Request
PATCH https://backstory.googleapis.com/v1/subjects/{subject_id}
Body Parameters
Parameter Name | Type | Required | Description |
roles
|
string
|
Yes | The role(s) the subject must have after the update. |
Sample Request
https://backstory.googleapis.com/v1/subjects/test@test.com
{
"subject": {
"name": "test@test.com",
"type": "SUBJECT_TYPE_ANALYST",
"roles": [
{
"name": "Test",
}
...
]
}
}
Response
Sample Response
{
"subject": {
"name": "test@test.com",
"type": "SUBJECT_TYPE_ANALYST",
"roles": [
{
"name": "Test",
"title": "Test role",
"description": "The test role",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
"isDefault": false,
"permissions": [
{
"name": "Test",
"title": "Test permission",
"description": "The test permission",
"createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
},
...
]
},
...
]
}
}
DeleteSubject
Deletes a subject.
Request
DELETE https://backstory.googleapis.com/v1/subjects/{subject_id}
URL Parameters
Parameter Name | Type | Required | Description |
subject_id | string | Yes | Unique identifier for the subject. |
Sample Request
https://backstory.googleapis.com/v1/subjects/test@test.com
Response
Returns an empty JSON with 200 OK, indicating the operation has completed successfully.