Gmail API

You can use the Rapid7 Gmail API plugin, instead of IMAP, to directly and programmatically access your email data. Use this plugin to monitor your organization’s emails, trigger workflows on unread emails received, batch modify message, and conduct other email actions. Find the full list of available triggers or actions in the Gmail API plugin documentation.

To configure the plugin, you will need to set up Gmail to accept API requests through a service account, and then authorize the account to take actions within your G Suite domain.

Create a Service Account

The Gmail API requires you to create a service account for a project, which in this case would be an integration with InsightConnect. Service accounts contain alternative credential sets to use with specific projects. This method of email configuration uses asymmetric key pairs to authorize and secure connections between Gmail and InsightConnect.

Account Privileges

You must have administrator-level privileges for your G Suite domain in order to set up this plugin. If you do not have these privileges, forward these instructions to someone in your organization who does.

To set up a service account for use with InsightConnect:

  1. Visit the Google API Console registration form at https://console.developers.google.com/start/api?id=gmail&credential=client_key to set up a service account. Google documentation for server-side authentication is found at https://developers.google.com/gmail/api/auth/web-server.
  • If this is your first time creating a Google API project, agree to the terms of service and select your country of residence. Then click Agree and Continue.
  • If you have created Google API projects in this Google account before, select “Create a Project” in the dropdown, then click Continue.
  1. Google will offer to help you figure out the credential type you need, but skip their default setup and click on the provided link for a service account instead. Find the line of text that says “If you wish you can skip this step and create an API key, client ID, or service account.”
  2. From the “Service accounts” panel, click + Create Service Account.
  3. Name your service account and provide a description of what the account will do. Google will generate a service account ID automatically. Then click Create.
  4. When prompted to add service account permissions, open the Role dropdown menu and select Project > Owner.
  5. Click the Continue button, then click + Create Key.
  6. Select the JSON key type, then click Create.
  7. Click Done.

After you create the service account, the JSON key will be saved to your browser’s default download location.

JSON File Security

This file can only be downloaded once. Do not lose it. It contains all of the connection information you will need to configure the Gmail plugin in InsightConnect. If it is lost, you will need to generate a new key and set up a new connection.

Anyone with access to this file will have almost everything they need to connect to your Gmail account. Ensure that the file is backed up and stored in a secure location!

Authorize your Service Account

Authorize your new service account to take actions within your G Suite domain.

To authorize your service account:

  1. Go to your Google Suite Admin console and click the Security tab. If you do not see it, look under the “More Controls” dropdown.
  2. Enter the service account’s client ID in the_ Client Name_ field. You can find the client ID in the JSON file you downloaded earlier.
  3. Enter https://mail.google.com in the One or More API Scopes field. If you require further configuration, click Learn More and enter one of the scopes defined in [https://developers.google.com/gmail/api/auth/scopes] (https://developers.google.com/gmail/api/auth/scopes).

Prepare the Private Key for InsightConnect

One of the items from the JSON file that you will need to configure in InsightConnect is the private key of the service account.

When entering the private key into the UI, you first need to ‘unescape’ it. ‘Unescaping’ changes escape sequences in the string back into the characters they represent. If you copy and paste the key directly from the JSON file, it will not work in InsightConnect as any /n newline escape characters will be read as-is.

To prepare the key for InsightConnect:

  1. Locate the credentials .json file you downloaded earlier.
  2. In a terminal window, run the command jq -rc .private_key <filename>.json. This will print the unescaped private key.
  3. Copy the unescaped key. You will use this to configure Gmail in InsightConnect.

You are now ready to add the connection in InsightConnect. Enter data from the JSON file into the corresponding input fields in InsightConnect, remembering to use the unescaped private key instead of copying the key directly from the JSON file.