GSuite for GMail v2.0.0

About the connector

G Suite comprises Gmail, Hangouts, Calendar, and Google+ for communication; Drive for storage; Docs, Sheets, Slides, Forms, and Sites for collaboration; and an Admin panel and Vault for managing users and the services.

This document provides information about the GSuite for Gmail connector, which facilitates automated interactions with GSuite for Gmail using FortiSOAR™ playbooks. Add the GSuite for Gmail connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching for emails using GSuite for Gmail, or deleting emails using GSuite for Gmail.

Version information

Connector Version: 2.0.0

Authored By: Community

Certified: No

Release Notes for version 2.0.0

The following enhancements have been made to the GSuite for Gmail Connector in version 2.0.0:

• Added the following operations and playbooks
  • Send Email
  • Modify Email Label
  • Import Email
• Added Support to OAuth Authorization.
• The following operations and playbooks have been updated along with their output schemas.
  • Search for Emails
  • Delete Emails

Accessing the Gmail API

Your application needs to be both authenticated and authorized to access the Gmail API. The REST APIs of Gmail allow you to manage asynchronous service-to-service communication used in serverless and micro-services architectures.

• Client ID
• Client Secret
• Redirect URI

The following configuration parameter is required to authorize the Gmail connector with the Gmail API.

• Authorization Code

You can get the authentication token to access the Gmail APIs using the OAuth 2.0 method. For more information see, https://developers.google.com/identity/protocols/oauth2/web-server.

You can follow the steps below to secure the authentication and authorization codes used to access the Gmail API:

1. Ensure that you have created a PROJECT in the Google Cloud Platform in the Web Application section so that you can get your CLIENT_ID, CLIENT_SECRET, and REDIRECT_URI, i.e., you must register your application with Gmail. For more information see, https://developers.google.com/adwords/api/docs/guides/authentication#webapp.
2. In the PROJECT, enable Gmail API and Admin SDK API in APIs and Services. For more information see, https://support.google.com/googleapi/answer/6158841?hl=en&ref_topic=7013279. Make a note of these authentication codes. In the Configurations tab of the connector, enter the authentication details in the following fields to authenticate the Gmail connector with the Gmail API.
   • In the Client ID field, enter the client ID
   • In the Client Secret field, enter the client secret
   • In the Redirect URL field, enter the redirect URI. By default, the redirect URI is set to https://localhost/myapp
     Now that you have the authentication codes, you can use them to generate the authorization code.
3. Copy the following URL into a browser and replace the CLIENT_ID and REDIRECT_URI with the client ID and redirect URI that was generated at the time of registering the application:
   https://accounts.google.com/o/oauth2/v2/auth?scope=https://mail.google.com/ https://www.googleapis.com/auth/admin.directory.user https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/gmail.send https://www.googleapis.com/auth/gmail.insert https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/admin.directory.user&access_type=offline&response_type=code&include_granted_scopes=true&state=state_parameter_passthrough_value&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID
4. Enter the link and you will be automatically redirected to a link with the following structure: REDIRECT_URI?state=STATE&code=AUTH_CODE&scope=SCOPE. Copy the AUTH_CODE (without the "code=" prefix), and in the Configurations tab of the connector, paste the AUTH_CODE in the Authorization Code field.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-gmail

Prerequisites to configuring the connector

• You must have the admin account's email address, for GSuite for Gmail, and the service account details in JSON format.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the Gmail server.

Minimum Permissions Required

• Not Applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the GSuite for Gmail connector card. On the connector popup, click the Configurations tab to enter the required configuration details:

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations:

operation: Send Email

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"threadId": "",
"labelIds": []
}

operation: Modify Email Label

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": "",
"threadId": "",
"labelIds": [],
"snippet": "",
"sizeEstimate": "",
"historyId": "",
"internalDate": ""
}

operation: Import Email

Input parameters

Output

The output contains the following populated JSON schema:
{
"id": ""
}

operation: Search for Emails

Input parameters

Output

The output contains the following populated JSON schema:
{
"messages": [
{
"id": "",
"threadId": ""
}
],
"nextPageToken": "",
"resultSizeEstimate": ""
}

operation: Delete Emails

Input parameters

Output

The output contains the following populated JSON schema:
{
"messages": ""
}

operation: List Users

Input parameters

Output

The output contains the following populated JSON schema:
{
"users": {},
"nextPage": ""
}

Included playbooks

The Sample - GSuite for Gmail - 2.0.0 playbook collection comes bundled with the GSuite for Gmail connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the GSuite for Gmail connector.

• Delete Emails
• Import Email
• List Users
• Modify Email Label
• Search for Emails
• Send Email

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.