GoogleApps API and G Suite

Use the GoogleApps API and G Suite integration to help administrators migrate to G Suite, create custom usage reports, and manage users, groups, and devices.

NOTE: The googleapps-gmail commands are deprecated, to execute Gmail commands, use the Gmail integration.


Prerequisites#

There are several procedures you have to perform in Google before configuring the integration on Demisto.


Get a New Private Key#

  1. Access your Google Service Account.

  2. In the IAM & admin section select Service accounts.

  3. If you need to create a new project, click CREATE do the following:

    1. In the New Project window, type a project name, select an organization from the drop-down list  and then select a location. 
    2. Click CREATE.
  4. In the Service accounts section, click Create Service Account.

  5. In the Create service account window, type a name for the service account, add a description and then click CREATE.

  6. Click Continue.

  7. In the Create key section, click CREATE KEY.

  8. Select Key type JSON and click CREATE.

  9. Click DONE.

    A key pair is generated and automatically downloads.

  10. In the Actions column, select the service and then click edit.

    mceclip1.png

  11. Under the show domain wide delegation, select Enable G Suite Domain-wide Delegation.

    gmail-_enable.png

     NOTE: Copy the value of the Unique ID for the client name in step 2 in Delegate Domain-wide Authority to Your Service Account.  

  12. Click Save.

  13. In the top search bar, search for admin sdk.

  14. Click Enable.

Delegate Domain-wide Authority to Your Service Account#

  1. Access the Google Administrator Console.

  2. Enter a client name and paste the following into the One or More API Scopes textbox.

    https://www.googleapis.com/auth/gmail.settings.basic,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.device.mobile.action,https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.settings.sharing,https://www.googleapis.com/auth/gmail.send,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/admin.directory.device.chromeos,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.directory.rolemanagement,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/gmail.readonly,https://mail.google.com,https://www.googleapis.com/auth/gmail.compose

GSuite API scopes#
API ScopeDescriptionDemisto command
https://mail.google.comReads, composes, sends, and permanently deletes all of the user's emails from Gmail.
  • gmail-get-autoreply
https://www.googleapis.com/auth/ admin.directory.device.chromeosViews and manages Chrome OS devices' metadata.
  • googleapps-chrome-device-action
  • googleapps-get-chrome-devices-for-user
  • googleapps-device-action
  • googleapps-get-devices-for-user
https://www.googleapis.com/auth/ admin.directory.device.mobile.actionManages mobile devices by performing administrative tasks.
  • googleapps-chrome-device-action
  • googleapps-get-chrome-devices-for-user
  • googleapps-device-action
  • googleapps-get-devices-for-user
https://www.googleapis.com/auth/ admin.directory.device.mobile.readonlyViews the metadata of a mobile device.
  • googleapps-chrome-device-action
  • googleapps-get-chrome-devices-for-user
  • googleapps-device-action
  • googleapps-get-devices-for-user
https://www.googleapis.com/auth/ admin.directory.rolemanagementManages delegated administration roles for the user's domain.
  • gmail-get-user-role
  • gmail-revoke-user-roles
https://www.googleapis.com/auth/ admin.directory.rolemanagement.readonlyViews delegated administration roles for the user's domain.
  • gmail-get-user-role
https://www.googleapis.com/auth/ admin.directory.userEnables full user management.
  • gmail-hide-user
  • gmail-set-user-password
  • gmail-create-user
  • gmail-delete-user
https://www.googleapis.com/auth/ admin.directory.user.readonlyViews users on your domain.
  • gmail-list-users
  • gmail-get-user
  • gmail-search-all-mailboxes
https://www.googleapis.com/auth/ admin.directory.user.securityManages data access permissions for users on your domain.
  • gmail-get-user-tokens
https://www.googleapis.com/auth/ gmail.composeSends a message on behalf of a user.
  • send-mail
https://www.googleapis.com/auth/ gmail.modifyViews and modifies but not deletes email.
  • gmail-get-autoreply
  • gmail-move-mail
  • gmail-move-mail-to-mailbox
  • gmail-delete-mail
https://www.googleapis.com/auth/ gmail.readonlyViews email messages and settings.
  • gmail-get-autoreply
  • gmail-search
  • gmail-search-all-mailboxes
  • gmail-get-mail
  • gmail-get-attachments
  • gmail-get-thread
  • fetch-incidents
https://www.googleapis.com/ auth/gmail.sendSends an email on behalf of someone else.
  • send-mail
https://www.googleapis.com/auth/ gmail.settings.basicManages basic mail settings.
  • gmail-get-autoreply
  • gmail-set-autoreply
  • gmail-add-filter
  • gmail-add-delete-filter
  • gmail-list-filters
  • gmail-remove-filter
https://www.googleapis.com/auth/ gmail.settings.sharingManages sensitive email settings, including who can manage emails.
  • gmail-delegate-user-mailbox
  • gmail-remove-delegated-mailbox

Get an Immutable Google Apps ID Parameters#

In order to revoke/fetch a user role, you need an Immutable Google Apps ID param.

  1. Open https://admin.google.com (as in step 2).

  2. Navigate to Security > Set up single sign-on (SSO).
    The SSO URL is the Immutable Google Apps ID.

  3. Record the SSO URL, which is the Immutable Google Apps ID, and copy it for later use.


Configure the GoogleApps (GSuite) Integration on Demisto#

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for GoogleApps API.
  3. Click Add instance to create and configure a new integration instance.
    • Name: a textual name for the integration instance.
    • Service account private key file content (JSON): Paste the¬†Service account JSON you generated in the Google console, which includes the JSON key. The¬†JSON might be long, so you can expand the text box.
    • Email of user with admin capabilities - Enter the email address of the user that you set¬†admin capabilities for.
    • Immutable Google Apps ID: Only the¬†Cxxxxxxxx, section is needed.
    • Import emails as incidents: Automatically creates Demisto incidents from received emails.
    • Events query - Use this to filter out the fetched messages.
      The query language follows the Gmail query specification example: "from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread". For more information, read the Gmail Query Language documentation.
    • Events user key- Use this¬†to specify the email account to search for messages. By default, the integration uses the email address specified in the admin instance.¬†¬†
    • Incident type
    • Demisto engine
  4. Click Test to validate the URLs and connection.

Commands#

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Perform an action on a Chrome device: googleapps-chrome-device-action
  2. Perform an action on a Google device: googleapps-device-action
  3. List all Chrome devices associated with a Google user: googleapps-get-chrome-devices-for-user
  4. List all devices associated with a Google user: googleapps-get-devices-for-user
  5. Get tokens for a Google user: googleapps-get-tokens-for-user
  6. Get information for a Google user: googleapps-get-user
  7. List all available Google roles: googleapps-get-user-roles
  8. Retrieve a Gmail message attachment: googleapps-gmail-get-attachment
  9. Retrieve a Gmail message: googleapps-gmail-get-mail
  10. Search a user's Gmail records: googleapps-gmail-search
  11. List all Google user: googleapps-list-users
  12. Revoke a Google user's role: googleapps-revoke-user-role

Perform an action on a Chrome device#

Performs one of several actions on a Google Chrome device.

Base Command#

googleapps-chrome-device-action

Input#
ParameterDescription
customerIdUnique identifier for the customer Google account. Use the !googleapps-get-user command to get this parameter. Default is my_customer.
actionAction to take on the Chrome OS device.
  • deprovision:¬†Remove a device from management that is no longer active, being resold, or is being submitted for return/repair
  • disable: Disable a device from being used, helpful in cases when a device is lost or stolen. You can configure the device screen to display a message explaining how to return the device.
  • reenable: Re-enable a
resource-idUnique ID the API service uses to identify the mobile device
tokenToken for authentication and authorization
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#

There is no context data for this command.

Raw Output#

Action executed.


Perform an action on a Google device#

Performs one of several actions on a Google device.

Base Command#

googleapps-device-action

Input#
ParameterDescription
customerIdUnique identifier for the customer Google account. Use the !googleapps-get-user command to get this parameter. Default is my_customer.
actionAction to take on the Chrome OS device.
  • admin_account_wipe: Remotely wipes only G Suite data from the device
  • admin_remote_wipe: Remotely wipes all data on the device
  • approve: Approves the device. If you selected Enable device activation, devices that register after the device activation setting is enabled require approval before they can begin syncing with your domain. Enabling device activation forces the device user to install the Device Policy app to sync with G Suite.
  • block:¬†Blocks access to G Suite data (mail, calendar, and contacts) on the device. The user can still access their mail, calendar, and contacts from a desktop computer or mobile browser.
  • cancel_remote_wipe_then_activate:¬†Cancels a remote wipe of the device and then reactivates the device
  • cancel_remote_wipe_then_block:¬†Cancels a remote wipe of the device and then blocks the device
resource-idUnique ID the API service uses to identify the mobile device
tokenToken for authentication and authorization
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#

There is no context data for this command.

Raw Output#

Action executed.


List all Chrome devices associated with a Google user#

Lists all Google Chrome devices associated with a specified Google user.

Base Command#

googleapps-get-chrome-devices-for-user

Input#
ParameterDescription
customerIdUnique identifier for the customer Google account. Use the !googleapps-get-user command to get this parameter. Default is my_customer.
actionAction to take on the Chrome OS device.
  • admin_account_wipe: Remotely wipes only G Suite data from the device
  • admin_remote_wipe: Remotely wipes all data on the device
  • approve: Approves the device. If you selected Enable device activation, devices that register after the device activation setting is enabled require approval before they can begin syncing with your domain. Enabling device activation forces the device user to install the Device Policy app to sync with G Suite.
  • block:¬†Blocks access to G Suite data (mail, calendar, and contacts) on the device. The user can still access their mail, calendar, and contacts from a desktop computer or mobile browser.
  • cancel_remote_wipe_then_activate:¬†Cancels a remote wipe of the device and then reactivates the device
  • cancel_remote_wipe_then_block:¬†Cancels a remote wipe of the device and then blocks the device
resource-idUnique ID the API service uses to identify the mobile device
tokenToken for authentication and authorization
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#
Device:[{
"BootMode": "",
"ActiveTimeRanges":"",
"recentUsersEmails":"",
"recentUsersTypes":"",
"AnnotatedAssetId":"",
"OrgUnitPath": "",
"AnnotatedLocation":"",
"EthernetMacAddress":"",
"FirmwareVersion":,
"DeviceId":"",
"LastEnrollmentTime":"",
"Meid":"",
"Notes": "",
"OrderNumber": "",
"Kind":"",
"PlatformVersion":"",
"SerialNumber": "",
"Model":"",
"SupportEndDate":"",
"OsVersion":"",
"Status":"",
"MacAddress":"",
"LastSync":""
}
]
Raw Output#
{
"kind": "directory#chromeosdevices",
"chromeosdevices": [
{
"kind": "directory#chromeosdevice",
"deviceId": "deviceId value",
"serialNumber": "device serialNumber",
"status": "ACTIVE",
"lastSync": "2013-03-05T17:30:04.325Z",
"supportEndDate": "2014-04-05T17:30:04.325Z",
"annotatedUser": "help desk",
"annotatedLocation": "Mountain View help desk Chromebook",
"annotatedAssetId": "1234567890",
"notes": "Loaned from support",
"orderNumber": "1234",
"willAutoRenew": true,
"osVersion": "Browser Version 18.0",
"platformVersion": "Platform Version 1415.2.0",
"firmwareVersion": "Firmware Version 1.2.3.4",
"bootMode": "validated",
"lastEnrollmentTime": "2012-04-05T17:30:04.325Z",
"orgUnitPath": "corp/engineering"
},
{
"kind": "directory#chromeosdevice",
"deviceId": "deviceId value",
"serialNumber": "device serialNumber",
"status": "SHIPPED",
"supportEndDate": "1404457200000",
"model": "model value",
"meid": "meid value",
"macAddress": "macAddress value",
"orderNumber": "1234",
"willAutoRenew": true
}
],
"nextPageToken": "nextPageToken value"
}

List all devices associated with a Google user#

Lists all devices associated with a specified Google user.

Base Command#

googleapps-get-devices-for-user

Input#
ParameterDescription
queryString to search for, enclosed in parentheses "". For more information, see the Google documentation.
customerIdUnique identifier for the customer Google account. Use the !googleapps-get-user command to get this parameter. Default is my_customer.
Context Data#
Device:[
{
"Applications": "",
"DevicePasswordStatus":"Off",
"Os":"Android 6.0.0",
"DeviceCompromisedStatus":"No compromise detected",
"Brand":,
"Imei": "",
"Hardware":"bullhead",
"ResourceId":,
"Model":,
"Name":[
"example example"
],
"DeviceId":,
"Status":"APPROVED",
"BootloaderVersion": ,
"Application Permissions": "",
"Kind":"admin#directory#mobiledevice",
"BuildNumber":,
"Applications Versions": "",
"DefaultLanguage":"English",
"WifiMacAddress":"",
"Type":"ANDROID",
"KernelVersion":,
"Packges":"",
"Email":"example@demisto.com,example@demisto.com.test-google-a.com",
"SerialNumber":
}
]
Raw Output#
{
"etag": "",
"kind": "admin#directory#mobiledevices",
"mobiledevices": [
{
"basebandVersion": "",
"bootloaderVersion": "",
"brand": "",
"buildNumber": "",
"defaultLanguage": "",
"deviceCompromisedStatus": "",
"deviceId": "",
"devicePasswordStatus": "",
"email": [
""
],
"encryptionStatus": "",
"etag": "",
"firstSync": "",
"hardware": "",
"hardwareId": "",
"kernelVersion": "",
"kind": "",
"lastSync": "",
"managedAccountIsOnOwnerProfile": "",
"manufacturer": "",
"model": "",
"name": [
""
],
"os": "",
"privilege": "",
"releaseVersion": "",
"resourceId": "",
"securityPatchLevel": "",
"serialNumber": "",
"status": "",
"supportsWorkProfile": "",
"type": "",
"userAgent": ""
}
]
}

Get tokens for a Google user#

Lists all tokens associated with a specified Google user.

Base Command#

googleapps-get-tokens-for-user

Input#
ParameterDescription
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#
{
Tokens:
{
ClientId:id.apps.googleusercontent.com
DisplayText:Google APIs Explorer
Kind:admin#directory#token
Scopes:https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly
UserKey:123456
}
}
Raw Output#
[
{
"clientId": "123.apps.googleusercontent.com",
"displayText": "Google APIs Explorer",
"etag": "",
"kind": "admin#directory#token",
"scopes": [
"https://www.googleapis.com/auth/admin.directory.device.mobile.action",
"https://www.googleapis.com/auth/admin.directory.rolemanagement"
],
"userKey": "123456"
}
]

Get information for a Google user#

Retrieves information for a specified Google user.

Base Command#

googleapps-get-user

Input#
ParameterDescription
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#
[
{
CustomerId: id
DisplayName:example example
Email:example@demisto.com
Group:admin#directory#user
ID:123456
Type:Google
UserName:example
}
]
Raw Output#
{
"agreedToTerms": true,
"creationTime": "2000-01-18T10:50:17.000Z",
"customerId": "",
"emails": [
{
"address": "example@demisto.com",
"primary": true
}
],
"etag": "",
"id": "123456",
"includeInGlobalAddressList": true,
"isAdmin": true,
"isMailboxSetup": true,
"kind": "admin#directory#user",
"lastLoginTime": "2000-01-28T12:16:07.000Z",
"name": {
"familyName": "example",
"fullName": "example example",
"givenName": "example"
},
"nonEditableAliases": [
"example@demisto.com.test-google-a.com"
],
"orgUnitPath": "/",
"primaryEmail": "example@demisto.com"
}

List all available Google roles#

Lists all available Google roles for a specified Google user.

Base Command#

googleapps-get-user-roles

Input#
ParameterDescription
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#
{
GoogleApps:
{
Role:[
{
AssignedTo:123456
ID:123456
Kind:admin#directory#roleAssignment
OrgUnitId:
RoleAssignmentId:123456
scopeType:CUSTOMER
}
]
}
}
Raw Output#
{
"etag": "",
"items": [
{
"assignedTo": "123456",
"etag": "",
"kind": "admin#directory#roleAssignment",
"roleAssignmentId": "123456",
"roleId": "123456",
"scopeType": "CUSTOMER"
}
],
"kind": "admin#directory#roleAssignments"
}

Retrieve a Gmail message attachment#

Retrieves a Gmail attachment sent to a specified Google user.

Base Command#

googleapps-gmail-get-attachment

Input#
ParameterDescription
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
attachment-idID of the attachment to retrieve
message-idID of the message to retrieve
Context Data#
{
"File": [
{
"Size":"",
"SHA1": "",
"SHA256": "",
"Name": "",
"EntryID": "",
"Info": "",
"Type": "",
"MD5": "",
"Extenstion": ""
}
]
}
Raw Output#

Requested file.


Retrieve a Gmail message#

Retrieves a Gmail message sent to a specified Google user.

Base Command#

googleapps-gmail-get-mail

Input#
ParameterDescription
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
attachment-idID of the attachment to retrieve
message-idID of the message to retrieve
Context Data#
{
"Email": [
{
"Body": "email body",
"Headers" : "From,To,Date,Content-Type",
"Attachments": [
{
"Name": ,
"ID": ,
}
],
"Format": "multipart/mixed",
"Type": "Gmail",
"ID": ,
"To": "example@demisto.com",
"Labels": "UNREAD, CATEGORY_PERSONAL, INBOX"
}
]
}
Raw Output#
{
"historyId": "17162",
"id": "16097d6a5bf2ae87",
"internalDate": "1514375913000",
"labelIds": [
"UNREAD",
"CATEGORY_PERSONAL",
"INBOX"
],
"payload": {
"body": {},
"headers": [
{
"name": "Delivered-To",
"value": "example@demisto.com"
}
],
"mimeType": "multipart/mixed",
"parts": [
{
"body": {},
"headers": [
{
"name": "To",
"value": "\\"example@demisto.com\\" &lt;example@demisto.com&gt;"
}
],
"mimeType": "multipart/alternative",
"partId": "0",
"parts": [
{
"body": {
"data": ,
"size": 253
},
"headers": [
{
"name": "Content-Type",
"value": "text/plain; charset=\\"iso-8859-1\\""
},
{
"name": "Content-Transfer-Encoding",
"value": "quoted-printable"
}
],
"mimeType": "text/plain",
"partId": "0.0"
}
]
},
{
"body": {
"attachmentId": ,
"size": 8264
},
"filename": ,
"headers": [
{
"name": "Content-Type",
"value": "application/octet-stream; name="
}
],
"mimeType": "application/octet-stream",
"partId": "1"
}
]
},
"sizeEstimate": 32967,
"snippet": ,
"threadId":
}

Search a user's Gmail records#

Searches the Gmail records of a specified Google user.

Base Command#

googleapps-gmail-search

Input#
ParameterDescription
user-keyEmail address of user that you want to search the mailbox for
queryOnly returns messages that match the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid: is:unread". For more syntax information, see the Google documentation.
fieldsComma-separated list that enables retrieval of partial responses. For more information, see the Google documentation.
include-spam-trashInclude messages labeled as SPAM and TRASH in the results, default is false.
label-idsComma-separated list that returns only messages with labels that match all of the specified label IDs.
max-resultsMaximum number of results to return Min-Max: 1-500 Default: 100
page-tokenPage token to retrieve a specific page of results in the list
Context Data#
{
"Email": [
{
"ID": <_GoogleApps unique message ID_>,
"ThreadId": &lt;GoogleApps unique thread ID&gt;,
"Type": "Gmail"
}
]
}
Raw Output#
{
"messages": [
{
"id": <_GoogleApps unique message ID_>,
"threadId": _&lt;GoogleApps unique thread ID&gt;_
}
],
"resultSizeEstimate": 1
}

List all Google user#

Lists all Google users.

Base Command#

googleapps-list-users

Input#

Either the domain _parameter or the _customer parameter is required.

ParameterDescription
domainDomain name. Use this field to get fields from only one domain. To return all domains for a customer account, use the customer query parameter.
customerUnique ID for the customer Google account, default is the value specified in the integration configuration
eventEvent on which subscription is intended (if subscribing). add delete makeAdmin undelete * update
custom-feed-maskComma-separated list of schema names. All fields from these schemas are fetched. Only set this parameter when the projection parameter is set to custom.
projectionThe subset of fields to fetch for the specified user. basic: Do not include any custom fields for the user (default) custom: Include custom fields from schemas requested in customFieldMask * full: Include all fields associated with the specified user
queryString to search for, enclosed in parentheses "". For more information, see the Google documentation.
show-deletedIf true, retrieves the list of deleted users, default is false
sort-orderHow to sort the results. Ascending Descending
tokenToken to authorize and authenticate the action
max-resultsMaximum number of results to return Min-Max: 1-500 Default: 100
Context Data#
{
"Account": [
{
"CustomerId": ,
"DisplayName": "example example",
"Email": "example@demisto.com",
"Group": "admin#directory#user",
"ID": _<Unique user_ ID>_,
_ "Type": "Google",
"UserName": "example"
}
]
}
Raw Output#
{
"etag": ,
"kind": "admin#directory#users",
"users": [
{
"agreedToTerms": true,
"creationTime": "2016-05-18T10:45:01.000Z",
"customerId": _<Customer_ _ID_>,
"emails": [
{
"address": "example@demisto.com",
"primary": true
}
],
"etag": <_eTag_>,
"id": _<Unique user_ ID>,
"includeInGlobalAddressList": true,
"isAdmin": true,
"isMailboxSetup": true,
"kind": "admin#directory#user",
"lastLoginTime": "2017-12-26T10:37:53.000Z",
"name": {
"familyName": "example",
"fullName": "example example",
"givenName": "example"
},
"nonEditableAliases": [
"example@demisto.com.test-google-a.com"
],
"orgUnitPath": "/",
"primaryEmail": "example@demisto.com",
"thumbnailPhotoEtag": ,
"thumbnailPhotoUrl": "https://plus.google.com/..."
}
]
}

Revoke a Google user's role#

Revokes roles for a specified Google users.

Base Command#

googleapps-revoke-user-role

Input#
ParameterDescription
role-assignment-idImmutable ID of the role assignment
tokenToken to authorize and authenticate the action
user-keyIdentifies the user specified in the API request. The value can be the user's primary email address, alias email address, or unique user ID.
Context Data#

There is no context data for this command.

Raw Output#
{DeletedRoleId: 123456}