Set up Chrome Browser Cloud Management

Use the Chrome Browser Cloud Management API

Topics

Authorization 

Before using all CBCM APIs, you will need to enable the Admin SDK API (if not already enabled) in the Google Developer Console by following this link and selecting the project on which you wish to enable the API.

From there, you have 2 choices of obtaining a token to access the API:

  1. Oauth2.0 with impersonation using a service account (Read below the section "Authorize With Impersonation")
  2. 3-legged Oauth2.0 without impersonation (You can authorize your requests following the Oauth2 Guideline)

The following scopes are needed to authorize your access to the CBCM API:

https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly

or

https://www.googleapis.com/auth/admin.directory.device.chromebrowsers

Authorize With Impersonation

To us a service account for impersonation, you need to:

  1.  Create a service account and have the necessary service account keys for this service account. You can follow this for creating a service account and getting the service account keys. 
  2. The client ID for this service account will need to be authorized for the OAuth scopes listed above. To do this, you must go to the Admin Console under Security -> API controls -> Manage domain wide delegation. You will then add a new client. On this dialog, the Client ID corresponds to the Unique ID of your service account.

With the service account keys, you will need to use the Google API Client Libraries of your preferred language to request an OAuth Access Token for your service account. 

 

Furthermore, the OAuth Token request will also need to impersonate an admin user in your domain when requesting the OAuth Token. 

As an example, here is some sample code using the Java API Client Libraries to retrieve the oauth token.

package takeout.api.credentials;

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;

public final class ApiRequestHelper {

  public static String getAccessToken(
      String serviceAccountKeyFilePath, String adminUserToImpersonate, Collection<String> scopes)
      throws IOException {
    InputStream is = new FileInputStream(serviceAccountKeyFilePath);

    GoogleCredential credential =
        GoogleCredential.fromStream(is).toBuilder()
            .setServiceAccountScopes(scopes)
            .setServiceAccountUser(adminUserToImpersonate)
            .build();

    if (!credential.refreshToken()) {
      throw new RuntimeException(
          String.format(
              "Failed to fetch refresh token for service account defined in '%s' for user '%s' and"
                  + " scopes '%s'",
              serviceAccountKeyFilePath, adminUserToImpersonate, String.join(",", scopes)));
    }
    return credential.getAccessToken();
  }

  public static void printUsage() {
    System.out.println(
        "Usage: get_access_token <service account key file> <admin user> [<scope,scope>]");
  }

  public static void main(String[] args) throws Exception {
    if (args.length < 2) {
      printUsage();
      return;
    }

    String scopes =
        "https://www.googleapis.com/auth/admin.directory.device.chromebrowsers";
    if (args.length >= 3) {
      scopes = args[2];
    }
    System.out.println(
        getAccessToken(args[0], args[1], new ArrayList<String>(Arrays.asList(scopes.split(",")))));
  }

  private ApiRequestHelper() {}
}

Using this sample code, you will be able to retrieve an access token which you can use to call the API. For example, if your key file is stored in /home/private_key.json and the admin account you want to use to make the request is admin@domain.com then you would run the exetuable with the following arguments:

ApiRequestHelper /home/private_key.json admin@domain.com

 

Note: The admin email used is not the e-mail of your service account (which is in the form <project-name>-<id>@<project-name>.iam.gserviceaccount.com).

ChromeBrowser

Chrome browsers enrolled in Chrome Browsers Cloud Management.

Resource Representation

The following JSON template is used for Chromebrowser resources in the Directory API:

{

"kind": "admin#directory#browserdevice",

"deviceId": string,

"osPlatform": string,

"osPlatformVersion": string,

"osArchitecture":string,

"osVersion": string,

"machineName": string,

"annotatedLocation": string,

"annotatedUser": string,

"annotatedAssetId": string,

"annotatedNotes": string,

"lastPolicyFetchTime": dateTime,

"lastRegistrationTime": dateTime,

"lastActivityTime":dateTime,

"lastStatusReportTime":dateTime,

"virtualDeviceId": string,

"serialNumber": string,

"orgUnitPath": string,

"extensionCount":int,

"policyCount": int,

"safeBrowsingClickThroughCount": int,

"lastDeviceUser": string,

"browserVersions": [string],

"lastDeviceUsers":[

  "userName": strin,

  "lastStatusReportTime":dateTime,

  ]

"machinePolicies": [

  "source": string,

  "name": string,

  "value": string,

  "error": string,

  ]

"browsers": [

  "browserVersion": string,

  "channel": string,

  "lastStatusReportTime": dateTime,

  "lastPolicyFetchTime": dateTime,

  "executablePath": string,

  "installedBrowserVersion": string,

  "plugins":[

    "name": string,

    "description": string,

    "fileame" string,

    ]

  "profiles": [

    "name": string,

    "id": string,

    "lastStatusReportTime": dateTime,

    "lastPolicyFectchTime": dateTime,

    "safeBrowsingWarnings": int,

    "safeBrowsingWarningsClickThrough": int,

    "chromeSignedinUserEmail": string,

    "extensionPolicies": [

      "extensionId": string,

      "extensionName": string,

      "policies": [

        "source": string,

        "name": string,

        "value": string,

        "error": string,

      ]

    ]

    "extensions": [

      "extensionId": string,

      "version": string,

      "permissions": [string],

      "name": string,

      "description":string,

      "appType": string,

      "homepageUrl": string,

      "installType": string,

      "configuredAppPolicy": string,

      "disabled": boolean,

      "icons": [

        "size": int,

        "url": string, 

      ]

    ]

    "userPolicies": [

      "source": string,

      "name": string,

      "value": string,

      "error": string,

    ]

    "safeBrowsingWarningsResetTime": string

  ]

}

Calling The API 

Retrieve all Chrome browser devices for an account 

Limitation: The nextPageToken returned by the listing request has a 1 hour lifetime. If your listing request has a large number of Chrome browser devices, your page token may expire before you can finish listing all the devices. In this case you may want to apply a filter to your listing request in order to reduce the number of devices returned by the query. Typically, filtering by OU is a good way to reduce the number of results.

 

To return a list of all Chrome Browser devices assigned to an account, use the following GET request and include the authorization described in Authorization. For readability, this code sample has line returns:

GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers?projection={FULL|BASIC}&query={query string}&orderBy={orderBy
category}&sortOrder={ASCENDING|DESCENDING}&pageToken={token for next results
page, if applicable &maxResults=max number of results per page}
  • The customerId is a unique identifier of the customer's Google account.
  • When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.

The following is a reference of all query string parameters that can be used in the request:

Parameter Type Description
maxResults integer Maximum number of results to return. Default, and maximum, is 100.
orderBy string Chrome browser device property to use for sorting results.
    Acceptable values for are
    "id" - The ID of the device with Chrome browser installed.
    "last_sync" - The date and time the Chrome browser device was either last registered, last synchronized with policy settings, or uploaded a report.
    "machine_name" - The name of the machine associated with the device.
    "extension_count" - Chrome browser device’s total number of extensions reported.
    "policy_count" - Chrome browser device’s total number of policies reported.
    "os_version" - OS of the device on which Chrome browser is installed.
    "last_signed_in_user" - Chrome browser device’s last signed in user.
    "annotated_user" - Chrome browser device user as annotated by the administrator.
    "annotated_location" - Chrome browser device location as annotated by the administrator.
    "annotated_asset_id" - Chrome browser device asset id as annotated by the administrator.
    "notes" - Chrome browser device notes as annotated by the administrator.
    "browser_version_channel" - The last Chrome version and channel reported by the device.
    "org_unit" - The Organizational Unit that the device is under.
    "enrollment_date" - The enrollment date of the device.
    "save_browsing_clickthrough" - Number of Safe Browsing click throughs this device has reported.
    "platform_major_version" - OS type and major version e.g.(Windows 10).:
    "last_activity" - The last activity time for the device.:
    "browser_version_sortable" - The oldest browser version installed on the device.:
    "os_version_sortable" - OS type and full version.:
orgUnitPath string The full path of the organizational unit or its unique ID.
pageToken string The pageToken query parameter is used to request the next page of query results. The follow-on request's pageToken query parameter is the nextPageToken from your previous response.
projection string Restrict information returned to a set of selected fields.
    Acceptable values are:
    "BASIC" - Includes only the basic metadata fields (i.e., the ones found in the columns of the admin console browser list as enumerated above)
    "FULL" - Includes all metadata fields (as enumerated above)
query string Search string using the list page query language described in the section below (Filter Query Language).
sortOrder string Whether to return results in ascending or descending order. Must be used with the orderBy parameter.
    Acceptable values are:
    "ASCENDING" - Ascending order.
    "DESCENDING" - Descending order.

Example: Filter devices by machine name

This first example searches for specific machine name by using query=machine_name:CLIENT2012. The response contains a single chrome browsers resource, where the machineName is help desk:

JSON request

GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers?projection=BASIC&query=machine_name:CLIENT2012&orderBy=status
&sortOrder=ASCENDING&maxResults=100

JSON response

A successful request returns an HTTP 200 status code. Along with a list of browsers devices that match your query paramaters:

{
  "kind": "directory#browserdevices",
  "browsers": [
     {
      "deviceId": "device_id_value",
      "kind": "admin#directory#browserdevice",
      "osPlatform": "Windows",
      "osVersion": "6.3.9600.19505",
      "machineName": "CLIENT2012",
      "lastRegistrationTime": "2019-11-04T00:29:17.484Z",
      "lastActivityTime": "2019-11-04T00:29:17.484Z",
      "virtualDeviceId": "virtual_device_id",
      "orgUnitPath": "/Org-unit path",
    },
  ],
  "nextPageToken": "abcdefghijkl123"
}

Retrieve a Chrome browser Device 

To retrieve a Chrome device's properties, use the following GET request and include the authorization described in Authorize requests. For readability, this code sample has line returns:

GET
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/deviceId?projection={FULL|BASIC}
  • The customerId is a unique identifier of the customer's Google account.
  • When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
  • The deviceId is a unique identifier for a device and is found in the response of the Retrieve all Chrome devices operation. For the query strings, request, and response properties, see the API Reference.

The following is a reference of all query string parameters that can be used in the request:

Parameter Type Description
deviceId string The unique ID of the device. The deviceIds are returned in the response from the browsersdevices.list method. Note: This parameter is required.
projection string Determines whether the response contains the full list of properties or only a subset.
    Acceptable values are:
    "BASIC": Includes only the basic metadata fields (i.e., the ones found in the columns of the admin console browsers list as enumerated above)
    "FULL": Includes all metadata fields (as enumerated above)

Example

JSON request

An example request. For readability, this code sample has line returns:

GET https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/deviceId?projection=basic

JSON response

A successful request returns an HTTP 200 status code. Along with the status code, the response returns the Chrome Browser device properties:

{
  "deviceId": "device_id_value",
  "kind": "admin#directory#browserdevice",
  "osPlatform": "Windows",
  "osVersion": "6.3.9600.19542",
  "machineName": "CLIENT2012",
  "lastRegistrationTime": "2019-11-27T12:55:27.230Z",
  "lastActivityTime": "2019-11-27T12:55:27.230Z",
  "virtualDeviceId": "virtual_device_id",
  "orgUnitPath": "/Org-unit path",
  "deviceIdentifiersHistory": { 
    "records": [
    { 
      "identifiers": { 
        "machineName": "CLIENT2012", 
        "serialNumber": "ABCD1234567890" }, 
      "firstRecordTime": "2019-11-27T12:55:27.230Z",
      "lastActivityTime": "2019-11-27T12:55:27.230Z"}
  ],
  “has_device_id_collision”: “false”
  }
}

Filter Query Language

 

When using the "query" parameter in a list request, every term in the query must be matched in a specific browser device in order to be valid. If you specify no operators (fields) in the query then the search will find a browser that has all the specified terms across all internally indexed text fields. For example if your query is: "query=machine 73", this will return a browser that has both the term "machine" and "73" in all the fields which could be returned in a browser device like the following:

{
  "deviceId": "device_id_value",
  "kind": "admin#directory#browserdevice",
  "osPlatform": "Windows",
  "osVersion": "6.3.9600.19542",
  "machineName": "machine_name",
  "browser_versions": [
    "73.0.0.0",
  ],
  "lastActivityTime": "2019-11-27T12:55:27.230Z",
  "virtualDeviceId": "virtual_device_id",
  "orgUnitPath": "/Org-unit path",
}

 

Note 1: Matching occurs on word boundaries (any punctuation or space) so that you would not be able to do partial matches on words. In the above example you would not be able to do query='mach 73'.

Note 2: Word matching is case insensitive so that a query with "machine" will match both "Machine" as well as "machine".

 

You can specify the following fields to target your search to specific fields (Note: although the query words are case insensitive, the field names are case sensitive).

Field Description
machine_name The machine name for the Chrome browser device.
os_platform The OS platform for the Chrome browser device. (e.g. Windows)
arch The CPU architecture for the Chrome browser device. (e.g. x86_64)
os_version The OS version for the chrome browser device. (e.g. 10.0.16299.904)
location The annotated location for the Chrome browser device.
user The annotated user for the Chrome browser device.
asset_id The annotated asset ID for the Chrome browser device.
note The annotated note for the Chrome browser device.
register The registration time for the Chrome browser device.
os The combine OS platform and major OS version for the Chrome browser device (e.g. "Windows 10")
browser_version A reported Chrome browser installed on the Chrome browser device (e.g. 73)
enrollment_token The enrollment token used to register the Chrome browser device.
report The last report time for the Chrome browser device
sync The last policy sync time for the Chrome browser device.
num_extensions The number of extensions reported by the Chrome browser device.
num_policies The number of policies reported by the Chrome browser device.
machine_user The last reported user of the Chrome browser device.
last_activity The last time the Chrome browser device has shown activity (policy fetch or reporting).
has_device_id_collision Device ID is shared by multiple machines that Chrome Browser identifies as the same machine. Supported values are true and false.

 

For fields that accept time (register, report, sync, last_activity) the time format is YYYY-MM-DDThh:mm:ss (e.g. 2020-01-01T12:00:00). You may also specify open or closed ranges for the time:

 

Form

Meaning

Examples

datetime

exactly on the given date or time

2011-03-23

2011-04-26T14:23:05

datetime..datetime

within (inclusive) the given interval of date or time

2011-03-23..2011-04-26

datetime..

on or after the given date or time

2011-04-26T14:23:05..

..datetime

on or before the given date or time

..2011-04-26T14:23:05

 

Example Filter Queries

 

Note 1: All provided examples use the 'query' parameter in the request. They parameter value must be properly escaped in the URL (i.e. to escape spaces with multi condition requests).

Note 2: All queries can further be filtered to a particular Organizational Unit by adding the 'orgUnitPath' query parameter to the request.

 

  1. Find all devices with machine name that contain a word:
    1. machine_name:LIX
  2. Find all devices with machine name that contain a word that were registered after a certain date:
    1. machine_name:LIX register:​2011-04-26..
  3. Find all devices with machine name that contain a word that were registered before a certain date:
    1. machine_name:LIX register:​..2011-04-26

 

Currently unsupported queries:

  1. Find all devices that have less than a certain number of extensions installed (range queries for numerical values is not supported).
  2. Find all devices that have a machine name that contains one of two possible words (using OR in queries).

 

Update a Chrome browser Device 

To update the annotated fields of a Chrome Browser devices assigned to an account, use the following PUT request and include the access token obtained by following the "Authorization" section. 

PUT
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/
devices/chromebrowsers/{deviceId}
  • The customerId is a unique identifier of the customer's Google account.
  • When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
  • The deviceId is a unique identifier for a device and is found in the response of the Retrieve all Chrome devices operation. For the query strings, request, and response properties, see the API Reference.

The following is a reference of all payload parameters that can be used in the request:

Parameter Required Type Description
deviceId required string The unique ID of the device. The deviceIds are returned in the response from the browsersdevices.list method. Note: This parameter is required.
annotatedUser optional string User of the device as annotated by the administrator.
annotatedLocation optional string

Address or location of the device as annotated by the administrator.

annotatedNotes optional string Notes about this device as annotated by the administrator
annotatedAssetId optional string

Asset identifier as annotated by the administrator or specified during enrollment.

Example

JSON request

An example request. For readability, this code sample has line returns:

PUT https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value

{

  "deviceId": "device_id_value",
  "annotatedUser": "user 1"
}

JSON response

A successful request returns an HTTP 200 status code. Along with the status code, the response returns the Chrome Browser device properties:

{
  "deviceId": "device_id_value",
  "kind": "admin#directory#browserdevice",
  "osPlatform": "Windows",
  "osVersion": "6.3.9600.19542",
  "machineName": "CLIENT2012",
  "lastRegistrationTime": "2019-11-27T12:55:27.230Z",
  "lastActivityTime": "2019-11-27T12:55:27.230Z",
  "virtualDeviceId": "virtual_device_id",
  "orgUnitPath": "/Org-unit path",
  "annotatedUser": "user 1"
}

 

Delete a Chrome browser Device 

To delete a Chrome Browser devices assigned to an account, use the following DELETE request and include the access token obtained by following the "Authorization" section. 

DELETE
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices
chromebrowsers/{deviceId}
  • The customerId is a unique identifier of the customer's Google account.
  • When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.
  • The deviceId is a unique identifier for a device and is found in the response of the Retrieve all Chrome devices operation. For the query strings, request, and response properties, see the API Reference.

Example

An example request:

DELETE https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/device_id_value

 

JSON response

A successful request returns an HTTP 200 status code. 

 

Move a Chrome browser Device between Organization Units 

To move Chrome Browser devices assigned to an account from one organization unit to another, use the following POST request and include the access token obtained by following the "Authorization" section. 

POST
https://www.googleapis.com/admin/directory/v1.1beta1/customer/{my_customer|customerId}/devices/chromebrowsers/moveChromeBrowsersToOu

 

  • The customerId is a unique identifier of the customer's Google account.
  • When impersonating an account administrator, you can also use the string my_customer which represents your account's customerId. Another way to get the customerId value is to use the Retrieve a user operation. Use your administrator email address or your administrator unique user id value in the operation's userKey path parameter.

The following is a reference of all payload parameters that can be used in the request:

Parameter Type Description
resource_ids List of string

List of unique device IDs of Chrome Browser Devices to move. A maximum of 600 browsers may be moved per request.

org_unit_path string

Destination organization unit to move devices to. Full path of the organizational unit or its ID prefixed with "id:"

 

Example

An example request.

POST https://www.googleapis.com/admin/directory/v1.1beta1/customer/my_customer/devices/
chromebrowsers/moveChromeBrowsersToOu
{
  "org_unit_path": "/new-path",
  "resource_ids": ["device_id_value_1","device_id_value_2"],
}

JSON response

A successful request returns an HTTP 200 status code. 

Was this helpful?
How can we improve it?