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.
Connector Version: 2.0.1
Authored By: Community
Certified: No
Following enhancements have been made to the GSuite for Gmail Connector in version 2.0.1:
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.
The following configuration parameter is required to authorize the Gmail connector with the Gmail API.
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:
https://localhost/myapp
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
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.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
For the procedure to configure a connector, click here
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:
Parameter | Description |
---|---|
Server URL | The service-based URL of the Google API server to which you will connect and perform the automated operations. |
Client ID | Unique ID of the Gmail application that is used to create an authentication token required to access the API. |
Client Secret | Unique Client Secret of the Google application that is used to create an authentication token required to access the API. For information on how to get the secret key, see Using OAuth 2.0 for Web Server Applications. |
Authorization Code | The authorization code that you have acquired during the authorization step. For more information, see the Accessing the Gmail API section. |
Redirect URL | The redirect_uri of your app, where you can send and receive the authentication responses. It must exactly match one of redirect_uri you registered in the app registration portal. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks and you can also use the annotations to access operations:
Function | Description | Annotation and Category |
---|---|---|
List Users | Lists the users in this domain based on the input parameters you have specified. | list_users Investigation |
Send Email | Sends an email with Jinja and email template support, based on the body type, content, content, and other input parameters you have specified. | send_email Investigation |
Modify Email Label | Adds or removes specified email labels from a specific message based on the message ID, email address, and other input parameters you have specified. | modify_email_label Investigation |
Search for Emails | Searches a user's emails based on the provided query like from: , to: , or subject: . |
search_emails Investigation |
Delete Emails | Deletes email messages from a user's mailbox based on the message IDs you have provided. | delete_messages Investigation |
Import Email | Imports a message into the specified user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP. It does not send a message. | import_email Investigation |
Parameter | Description |
---|---|
Email Address | Specify the email address of the user who is sending the emails. |
To Recipients | Specify the email addresses of the recipients in the To field. You can add multiple email addresses by separating them with a comma (Comma Separated Value). For example, abc@xyz.com, def@lmn.com . |
Subject | Specify the subject of the email that you are sending from the Gmail account. |
Cc Recipients | (Optional) Specify the email addresses of the recipients in the Cc field. You can add multiple email addresses by separating them with a comma (Comma Separated Value). For example, abc@xyz.com, def@lmn.com . |
Bcc Recipients | (Optional) Specify the email addresses of the recipients in the Bcc field. You can add multiple email addresses by separating them with a comma (Comma Separated Value). For example, abc@xyz.com, def@lmn.com . |
Body | (Optional) Specify the message or content of the email that you are sending from the Gmail account. |
Message ID | (Optional) Specify the immutable ID of the message. Note: You can retrieve the ID using the Search Emails operation. |
Attachment ID | (Optional) Specify the ID of the external attachment which you can retrieve using messages.attachments.get request. When not specified, the entire content of the email body's message part is contained in the data field. |
Label IDs | (Optional) Specify a JSON array list of Label IDs you want to apply to this message. |
Thread ID | (Optional) Specify the ID of the parent thread which includes this message. |
Part ID | (Optional) Specify the immutable ID of the email body's message part. |
History ID | (Optional) Specify the last history's record ID that modified this message. |
Internal Date | (Optional) Specify the internal message creation timestamp (in epoch milliseconds) that determines the order of emails in the inbox. |
Headers | (Optional) Specify a JSON array list of headers for this email's message part. The top-level message part, representing the entire message payload, contains the standard RFC 2822 email headers such as To, From, Cc, Bcc, and Subject. |
Data | (Optional) Specify the body data of a MIME message part as a base64url encoded string. It may be empty for MIME container types that have no message body or when the body data is sent as a separate attachment. An attachment ID is present if the body data is contained in a separate attachment. |
Size | (Optional) Specify the number of bytes for the message part data (excluding the encoding). |
Filename | (Optional) Specify the filename of the attachment. Only present if this message part represents an attachment. |
Snippet | (Optional) Specify a short segment of the message text. |
Mime Type | (Optional) Specify the MIME type of message part. |
Estimate Size | (Optional) Specify the estimated size of the message in bytes. |
Parts | (Optional) Specify the child MIME message parts of this part. This only applies to container MIME message parts, for example multipart/* . For non-container MIME message part types, such as text/plain , this field is empty. For more information, see RFC 1521. |
The output contains the following populated JSON schema:
{
"id": "",
"threadId": "",
"labelIds": []
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user whose mailbox labels are being modified. |
Message ID | Specify the ID of the message whose label is being modified. |
Remove Label IDs | (Optional) Specify a list of label IDs of labels to remove from this message. |
Add Label IDs | (Optional) Specify a list of label IDs of labels to add to this message. |
The output contains the following populated JSON schema:
{
"id": "",
"threadId": "",
"labelIds": [],
"snippet": "",
"sizeEstimate": "",
"historyId": "",
"internalDate": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user in whose mailbox the emails are being imported. |
To Recipients | Specify the Comma-separated list of recipients' email addresses, to whom the emails being imported were sent, in the To field. For example: abc@xyz.com,def@lmn.com . |
Subject | (Optional) Specify the subject of the email messages being imported. |
Cc Recipients | (Optional) Specify the comma-separated list of recipients' email addresses, to whom the emails being imported were sent, in the Cc field. For example: abc@xyz.com,def@lmn.com . |
Bcc Recipients | (Optional) Specify the comma-separated list of recipients' email addresses, to whom the emails being imported were sent, in the Bcc field. For example: abc@xyz.com,def@lmn.com . |
Body | (Optional) Specify the message or content of the emails being imported. |
Message ID | (Optional) Specify the immutable ID of the emails being imported. Note: You can retrieve the ID using the Search Emails operation. |
Attachment ID | (Optional) Specify the ID of the external attachment which you can retrieve using messages.attachments.get request. When not present, the entire content of the email body's message part is contained in the data field. |
Label IDs | (Optional) Specify the comma-separated list of label IDs of the emails being imported. |
Thread ID | (Optional) Specify the ID of the parent thread which includes this message being imported. |
Part ID | (Optional) Specify the immutable ID of the email body's message part. |
History ID | (Optional) Specify the last history's record ID that modified this message. |
Internal Date | (Optional) Specify the internal message creation timestamp (in epoch milliseconds) of the emails being imported. |
Headers | (Optional) Specify a JSON array list of headers for the imported email's message part. The top-level message part, representing the entire message payload, contains the standard RFC 2822 email headers such as To, From, Cc, Bcc, and Subject. |
Data | (Optional) Specify the body data of a MIME message part, of the email being imported, as a base64url encoded string. It may be empty for MIME container types that have no message body or when the body data is sent as a separate attachment. An attachment ID is present if the body data is contained in a separate attachment. |
Size | (Optional) Specify the number of bytes for the message part data (excluding the encoding), of the emails being imported. |
Filename | (Optional) Specify the filename of the attachment in the email being imported. Specify only present if this message part represents an attachment. |
Snippet | (Optional) Specify a short segment of the message text for the email being imported. |
Mime Type | (Optional) Specify the MIME type of message part of the email being imported. |
Estimate Size | (Optional) Specify the estimated size of the message in bytes of the emails being imported. |
Parts | (Optional) Specify the child MIME message parts of part of the email being imported. This only applies to container MIME message parts, for example multipart/* . For non-container MIME message part types, such as text/plain , this field is empty. For more information, see RFC 1521. |
The output contains the following populated JSON schema:
{
"id": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user in whose mailbox the emails are being searched. |
Query | (Optional) Specify the search query for searching emails in the targeted user's inbox. This can use specifiers such as from: , subject: , or To: . |
Label IDs | (Optional) Specify a comma-separated list of label IDs of the labels associated with emails being searched. |
Include Message SPAM/Trash | (Optional) Specify if you want to include messages from SPAM and TRASH in the search results. |
Page Token | (Optional) Specify the page token to fetch the next page of a previously run search query. |
The output contains the following populated JSON schema:
{
"messages": [
{
"id": "",
"threadId": ""
}
],
"nextPageToken": "",
"resultSizeEstimate": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user from whose mailbox the emails are being deleted. |
Message IDs | Specify the semicolon-delimited list of message IDs to be deleted. |
The output contains the following populated JSON schema:
{
"messages": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the admin account associated with GSuite for Gmail. |
Page Token | (Optional) Specify the page token to fetch the next page of a previously run search query. |
The output contains the following populated JSON schema:
{
"users": {},
"nextPage": ""
}
The Sample - GSuite for Gmail - 2.0.1
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.
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.
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.
Connector Version: 2.0.1
Authored By: Community
Certified: No
Following enhancements have been made to the GSuite for Gmail Connector in version 2.0.1:
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.
The following configuration parameter is required to authorize the Gmail connector with the Gmail API.
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:
https://localhost/myapp
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
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.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
For the procedure to configure a connector, click here
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:
Parameter | Description |
---|---|
Server URL | The service-based URL of the Google API server to which you will connect and perform the automated operations. |
Client ID | Unique ID of the Gmail application that is used to create an authentication token required to access the API. |
Client Secret | Unique Client Secret of the Google application that is used to create an authentication token required to access the API. For information on how to get the secret key, see Using OAuth 2.0 for Web Server Applications. |
Authorization Code | The authorization code that you have acquired during the authorization step. For more information, see the Accessing the Gmail API section. |
Redirect URL | The redirect_uri of your app, where you can send and receive the authentication responses. It must exactly match one of redirect_uri you registered in the app registration portal. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks and you can also use the annotations to access operations:
Function | Description | Annotation and Category |
---|---|---|
List Users | Lists the users in this domain based on the input parameters you have specified. | list_users Investigation |
Send Email | Sends an email with Jinja and email template support, based on the body type, content, content, and other input parameters you have specified. | send_email Investigation |
Modify Email Label | Adds or removes specified email labels from a specific message based on the message ID, email address, and other input parameters you have specified. | modify_email_label Investigation |
Search for Emails | Searches a user's emails based on the provided query like from: , to: , or subject: . |
search_emails Investigation |
Delete Emails | Deletes email messages from a user's mailbox based on the message IDs you have provided. | delete_messages Investigation |
Import Email | Imports a message into the specified user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP. It does not send a message. | import_email Investigation |
Parameter | Description |
---|---|
Email Address | Specify the email address of the user who is sending the emails. |
To Recipients | Specify the email addresses of the recipients in the To field. You can add multiple email addresses by separating them with a comma (Comma Separated Value). For example, abc@xyz.com, def@lmn.com . |
Subject | Specify the subject of the email that you are sending from the Gmail account. |
Cc Recipients | (Optional) Specify the email addresses of the recipients in the Cc field. You can add multiple email addresses by separating them with a comma (Comma Separated Value). For example, abc@xyz.com, def@lmn.com . |
Bcc Recipients | (Optional) Specify the email addresses of the recipients in the Bcc field. You can add multiple email addresses by separating them with a comma (Comma Separated Value). For example, abc@xyz.com, def@lmn.com . |
Body | (Optional) Specify the message or content of the email that you are sending from the Gmail account. |
Message ID | (Optional) Specify the immutable ID of the message. Note: You can retrieve the ID using the Search Emails operation. |
Attachment ID | (Optional) Specify the ID of the external attachment which you can retrieve using messages.attachments.get request. When not specified, the entire content of the email body's message part is contained in the data field. |
Label IDs | (Optional) Specify a JSON array list of Label IDs you want to apply to this message. |
Thread ID | (Optional) Specify the ID of the parent thread which includes this message. |
Part ID | (Optional) Specify the immutable ID of the email body's message part. |
History ID | (Optional) Specify the last history's record ID that modified this message. |
Internal Date | (Optional) Specify the internal message creation timestamp (in epoch milliseconds) that determines the order of emails in the inbox. |
Headers | (Optional) Specify a JSON array list of headers for this email's message part. The top-level message part, representing the entire message payload, contains the standard RFC 2822 email headers such as To, From, Cc, Bcc, and Subject. |
Data | (Optional) Specify the body data of a MIME message part as a base64url encoded string. It may be empty for MIME container types that have no message body or when the body data is sent as a separate attachment. An attachment ID is present if the body data is contained in a separate attachment. |
Size | (Optional) Specify the number of bytes for the message part data (excluding the encoding). |
Filename | (Optional) Specify the filename of the attachment. Only present if this message part represents an attachment. |
Snippet | (Optional) Specify a short segment of the message text. |
Mime Type | (Optional) Specify the MIME type of message part. |
Estimate Size | (Optional) Specify the estimated size of the message in bytes. |
Parts | (Optional) Specify the child MIME message parts of this part. This only applies to container MIME message parts, for example multipart/* . For non-container MIME message part types, such as text/plain , this field is empty. For more information, see RFC 1521. |
The output contains the following populated JSON schema:
{
"id": "",
"threadId": "",
"labelIds": []
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user whose mailbox labels are being modified. |
Message ID | Specify the ID of the message whose label is being modified. |
Remove Label IDs | (Optional) Specify a list of label IDs of labels to remove from this message. |
Add Label IDs | (Optional) Specify a list of label IDs of labels to add to this message. |
The output contains the following populated JSON schema:
{
"id": "",
"threadId": "",
"labelIds": [],
"snippet": "",
"sizeEstimate": "",
"historyId": "",
"internalDate": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user in whose mailbox the emails are being imported. |
To Recipients | Specify the Comma-separated list of recipients' email addresses, to whom the emails being imported were sent, in the To field. For example: abc@xyz.com,def@lmn.com . |
Subject | (Optional) Specify the subject of the email messages being imported. |
Cc Recipients | (Optional) Specify the comma-separated list of recipients' email addresses, to whom the emails being imported were sent, in the Cc field. For example: abc@xyz.com,def@lmn.com . |
Bcc Recipients | (Optional) Specify the comma-separated list of recipients' email addresses, to whom the emails being imported were sent, in the Bcc field. For example: abc@xyz.com,def@lmn.com . |
Body | (Optional) Specify the message or content of the emails being imported. |
Message ID | (Optional) Specify the immutable ID of the emails being imported. Note: You can retrieve the ID using the Search Emails operation. |
Attachment ID | (Optional) Specify the ID of the external attachment which you can retrieve using messages.attachments.get request. When not present, the entire content of the email body's message part is contained in the data field. |
Label IDs | (Optional) Specify the comma-separated list of label IDs of the emails being imported. |
Thread ID | (Optional) Specify the ID of the parent thread which includes this message being imported. |
Part ID | (Optional) Specify the immutable ID of the email body's message part. |
History ID | (Optional) Specify the last history's record ID that modified this message. |
Internal Date | (Optional) Specify the internal message creation timestamp (in epoch milliseconds) of the emails being imported. |
Headers | (Optional) Specify a JSON array list of headers for the imported email's message part. The top-level message part, representing the entire message payload, contains the standard RFC 2822 email headers such as To, From, Cc, Bcc, and Subject. |
Data | (Optional) Specify the body data of a MIME message part, of the email being imported, as a base64url encoded string. It may be empty for MIME container types that have no message body or when the body data is sent as a separate attachment. An attachment ID is present if the body data is contained in a separate attachment. |
Size | (Optional) Specify the number of bytes for the message part data (excluding the encoding), of the emails being imported. |
Filename | (Optional) Specify the filename of the attachment in the email being imported. Specify only present if this message part represents an attachment. |
Snippet | (Optional) Specify a short segment of the message text for the email being imported. |
Mime Type | (Optional) Specify the MIME type of message part of the email being imported. |
Estimate Size | (Optional) Specify the estimated size of the message in bytes of the emails being imported. |
Parts | (Optional) Specify the child MIME message parts of part of the email being imported. This only applies to container MIME message parts, for example multipart/* . For non-container MIME message part types, such as text/plain , this field is empty. For more information, see RFC 1521. |
The output contains the following populated JSON schema:
{
"id": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user in whose mailbox the emails are being searched. |
Query | (Optional) Specify the search query for searching emails in the targeted user's inbox. This can use specifiers such as from: , subject: , or To: . |
Label IDs | (Optional) Specify a comma-separated list of label IDs of the labels associated with emails being searched. |
Include Message SPAM/Trash | (Optional) Specify if you want to include messages from SPAM and TRASH in the search results. |
Page Token | (Optional) Specify the page token to fetch the next page of a previously run search query. |
The output contains the following populated JSON schema:
{
"messages": [
{
"id": "",
"threadId": ""
}
],
"nextPageToken": "",
"resultSizeEstimate": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the user from whose mailbox the emails are being deleted. |
Message IDs | Specify the semicolon-delimited list of message IDs to be deleted. |
The output contains the following populated JSON schema:
{
"messages": ""
}
Parameter | Description |
---|---|
Email Address | Specify the email address of the admin account associated with GSuite for Gmail. |
Page Token | (Optional) Specify the page token to fetch the next page of a previously run search query. |
The output contains the following populated JSON schema:
{
"users": {},
"nextPage": ""
}
The Sample - GSuite for Gmail - 2.0.1
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.
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.