Skip to content

Cloud Identity Devices

Jump to bottom
Ross Scroggs edited this page Dec 10, 2020 · 22 revisions

Cloud Identity Devices

API documentation

Query documentation

Definitions

<AssetTag> ::= <String>
<AssetTagList> ::= "<AssetTag>(,<AssetTag>)*"
<QueryDevice> ::= <String>
        See: https://support.google.com/a/answer/7549103
<QueryDeviceList> ::= "<QueryDevice>(,<QueryDevice>)*"
<DeviceID> ::= devices/<String>
<DeviceEntity> ::=
        <DeviceIDList> |
        (query:<QueryDevice>)|(query <QueryDevice>)
<DeviceType> ::= android|chrome_os|google_sync|ios|linux|mac_os|windows
<DeviceUserID> ::= devices/<String>/deviceUsers/<String>
<DeviceUserEntity> ::=
        <DeviceUserIDList> |
        (query:<QueryDevice>)|(query <QueryDevice>)

<DeviceFieldName> ::=
        androidspecificattributes|
        assettag|
        basebandversion|
        bootloaderversion|
        brand|
        buildnumber|
        compromisedstate|
        createtime|
        devicetype|
        enableddeveloperoptions|
        enabledusbdebugging|
        encryptionstate|
        imei|
        kernelversion|
        lastsynctime|
        managementstate|
        manufacturer|
        meid|
        model|
        name|
        networkoperator|
        osversion|
        otheraccounts|
        ownertype|
        releaseversion|
        securitypatchtime|
        serialnumber|
        wifimacaddresses
<DeviceFieldNameList> ::= "<DeviceFieldName>(,<DeviceFieldName>)*"

<DeviceAction> ::=
        cancelwipe|
	wipe

<DeviceUserFieldName> ::=
        compromisedstate|
        createtime|
        firstsyncime|
        languagecode|
        lastsynctime|
        managementstate|
        name|
        passwordstate|
        useragent|
        useremail
<DeviceUserFieldNameList> ::= "<DeviceUserFieldName>(,<DeviceUserFieldName>)*"

<DeviceOrderbyFieldName> ::= 
        createtime|devicetype|lastsynctime|model|osversion|serialnumber

<DeviceUserAction> ::=
        approve|
        block|
        cancelwipe|
	wipe

Create a company device

Adds a new device to the Google company-owned inventory. Once a user is assigned and enrolled on the device the device will be considered company-owned for management purposes. The device will also register as company-owned with Google services like Context-Aware Access (CAA).

gam create device serialnumber <String> devicetype <DeviceType> [assettag <String>]

Arguments serialnumber <String> and devicetype <DeviceType> are required; you can optionally specify assettag <String>.

Delete devices

Delete a device from appearing in the Admin console, stop syncing for the device user. No user data should be removed.

gam delete device <DeviceEntity> [doit]

If <DeviceEntity> uses a query, the doit option must be used to enable execution.

Wipe devices

Wiping a device performs a factory reset, all device data is removed.

gam cancelwipe device <DeviceEntity> [doit]
gam wipe device <DeviceEntity> [doit]

If <DeviceEntity> uses a query, the doit option must be used to enable execution.

Perform device actions

This is an alternative form of the above commands

gam update device <DeviceEntity> action <DeviceAction> [doit]

If <DeviceEntity> uses a query, the doit option must be used to enable execution.

Synchronize devices

This command generates a list of your current company devices, either a complete list or a subset based on a query. A CSV file is read to generate another list of devices.

At a minimum, two values are required for devices in the CSV file list; a device type and a serial number. For the device type, you can either specify a static device type or specify the column in the CSV file that contains a device type.

  • static_devicetype <DeviceType> - A fixed device type
  • devicetype_column <String> - The name of the column containing device types; if not specified, deviceType is used

For the serial number, you must specify the column in the CSV file that contains a serial number.

  • serialnumber_column <String> - The name of the column containing serial numbers; if not specified, serialNumber is used

You can optionally specify the column in the CSV file that contains an asset tag.

  • assettag_column <String> - The name of the column containing asset tags; the typical value is assetTag

These two/three columns are used to match current company devices against the CSV file devices.

  • Devices in the CSV device list will be created if they are not the the current company device list.
  • Devices in the current company device list that are not in the CSV device list will have an optional operation performed on them.
    • unassigned_missing_action delete|wipe|none - Perform this operation if the company device has never been assigned; default action is delete
    • assigned_missing_action delete|wipe|none - Perform this operation if the company device has been assigned; default action is none

If preview is specified, the operations that would be performed are previewed but are not performed; use this to test.

gam sync devices
        [(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime.* <Time>)*]
        csvfile <FileName>
        (devicetype_column <String>)|(static_devicetype <DeviceType>)
        (serialnumber_column <String>)
        [assettag_column <String>]
        [unassigned_missing_action delete|wipe|donothing]
        [assigned_missing_action delete|wipe|donothing]
        [preview]

Display devices

gam info device <DeviceEntity>
        <DeviceFieldName>* [fields <DeviceFieldNameList>] [userfields <DeviceUserFieldNameList>]
        [nodeviceusers]
        [formatjson]

By default, Gam displays the information as an indented list of keys and values.

  • formatjson - Display the fields in JSON format.

Print devices

gam print devices [todrive <ToDriveAttribute>*]
        [(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime.* <Time>)*]
        <DeviceFieldName>* [fields <DeviceFieldNameList>] [userfields <DeviceUserFieldNameList>]
        [orderby <DeviceOrderByFieldName> [ascending|descending]]
        [all|company|personal|nocompanydevices|nopersonaldevices]
        [nodeviceusers]
        [formatjson [quotechar <Character>]]

Select the view of devices to display:

  • all - Company and personal devices; this is the default
  • company|nopersonaldevices - Company devices
  • personal|nocompanydevices - Personal devices

To AND query terms, put all of your terms in one query:

gam print devices query "manufacturer:Meizu os:Android 7.0.0"

To OR query terms, put the terms im multiple queries:

gam print devices queries "'model:iPhone 6','model:samsung'"

By default, Gam displays the information as columns of fields; the following option causes the ouput to be in JSON format,

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char.

Approve or block device users

Approve or block user profiles on a device.

gam approve deviceuser <DeviceUserEntity> [doit]
gam block deviceuser <DeviceUserEntity> [doit]

If <DeviceUserEntity> uses a query, the doit option must be used to enable execution.

Delete device users

Delete a device user from appearing in the Admin console, stop syncing for the device user. No user data should be removed.

gam delete deviceuser <DeviceUserEntity> [doit]

If <DeviceUserEntity> uses a query, the doit option must be used to enable execution.

Wipe device users

Wipe a device user profile from a device. In the case of Android for Work, the work profile will be removed but the personal profile left alone.

gam wipe deviceuser <DeviceUserEntity> [doit]
gam cancelwipe deviceuser <DeviceUserEntity> [doit]

If <DeviceUserEntity> uses a query, the doit option must be used to enable execution.

Perform device user actions

This is an alternative form of the above commands.

gam update deviceuser <DeviceUserEntity> action <DeviceUserAction> [doit]

If <DeviceUserEntity> uses a query, the doit option must be used to enable execution.

Display device users

gam info deviceuser <DeviceUserEntity>
        <DeviceUserFieldName>* [fields <DeviceUserFieldNameList>]
        [formatjson]

Print device users

gam print deviceusers [todrive <ToDriveAttribute>*]
        [(query <QueryDevice>)|(queries <QueryDeviceList>) (querytime.* <Time>)*]
        <DeviceUserFieldName>* [fields <DeviceUserFieldNameList>]
        [orderby <DeviceOrderByFieldName> [ascending|descending]]
        [formatjson [quotechar <Character>]]

By default, Gam displays the information as columns of fields; the following option causes the ouput to be in JSON format,

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char.

Display device user client state

gam info deviceuserstate <DeviceUserEntity> [clientid <String>]

Update device user client state

The API that supports this command is in beta mode. In particular, setting assettags and customvalues works if you set the values once; each additional time you set values they are added to the existing values and they is no way at the moment to clear values.

gam update deviceuserstate <DeviceUserEntity> [clientid <String>] 
        [customid <String>] [assettags clear|<AssetTagList>]
        [compliantstate|compliancestate compliant|noncompliant] [managedstate clear|managed|unmanaged]
        [healthscore very_poor|poor|neutral|good|very_good] [scorereason clear|<String>]
        (customvalue (bool|boolean <Boolean>)|(number <Integer>)|(string <String>))*

Need more help? Ask on the GAM Discussion Group

Update History

Installation

Configuration

Notes and Information

Definitions

Command Processing

Collections

Client Access

Special Service Account Access

Service Account Access

Clone this wiki locally