Onboarding Google Workspace [API]

This page includes:

About onboarding Google Workspace using the Google API

You can connect your Google Workspace-based email services to FortiMail Workspace Security – using the Google API. This is called the Google Workspace API connection method.

This page describes how to integrate FortiMail Workspace Security with Google Workspace using the Google Workspace API connection method. For details on how to integrate FortiMail Workspace Security with Google Workspace using the inline connection method, see Step 1 - Onboarding Google Workspace [Inline].

Note: With Google Workspace API integrations, FortiMail Workspace Security scans email messages up to a maximum size of 500 MB [including attachments].

By default, Google Workspace API integrations monitor incoming emails only - not outgoing emails, nor internal emails. [Internal emails are emails that are sent between protected domains in the same organization.]

For information about configuring scanning of outgoing email, see Onboarding Google Workspace - Outbound.

Note:

  • After onboarding a Google Workspace API integration, you can change the set of assets that are protected by FortiMail Workspace Security. Changing the set of assets includes:

    • deleting any of the specified domains or users

    • specifying additional domains or users

    For details, see Editing the protected assets.

  • You can specify a maximum of 300 assets [domains and users] to protect.

A bit more about the Google Workspace API integration

Onboarding process

  • API scanning initiates by creating a Webhook for each user within the Google Workspace environment.

Protection mechanism

  • When a user is protected by FortiMail Workspace Security Google Workspace API integration, the scan activates upon the arrival of an inbound email.

  • Google Workspace triggers a notification to the scanning system about a new email in the user's Inbox.

  • The system retrieves the email's metadata and EML file copy for analysis.

Scan and response

  • Clean: If an email is assigned a clean verdict, the email remains in the user's Inbox - without any intervention.

  • Spam: By default, spam emails are moved to the Spam folder via Google API calls.

  • Malicious: By default, malicious inbound emails are deleted from the recipient's mailbox.

    Note: End users may see malicious emails in their inboxes for a few seconds before the scan is completed and the email is deleted.

How to onboard Google Workspace using the Google API

This onboarding procedure for a Google Workspace API integration includes:

  • Specifying the connection method.

  • Enabling the FortiMail Workspace Security app - that enables the required access to your Google Workspace account.

  • Specifying who to protect [the plan].

  • Initiating the connection process.

To onboard Google Workspace using the Google API:

  1. In FortiMail Workspace Security, select Settings > Bundles and Channels.

  2. Under Enabled Channels, locate Email Service, and then click Email service configuration [] on the right.

  3. Click Add A New Email Service - if this option appears.

    The "Add a New Service" dialog box will open.

  4. Select the Organization - if necessary.

    Note: Make sure to select the organization in which the scanning will occur. This is typically a child organization - not a parent organization.

  5. Specify the Escalation contacts. For details, see Escalation contacts.

  6. In Email Service, select Google Workspace.

  7. In Connection Method, select Google API.

    Connection Scope:

    1. Inbound: Will be automatically selected. This configures FortiMail Workspace Security to scan emails that are received from outside the organization.

    2. Outbound: [Optional] This configures FortiMail Workspace Security to scan emails that are sent from inside the organization. This option appears only if outbound scanning is enabled. For details, see Onboarding Microsoft 365 - Outbound.

      Note: By default, internal email is not monitored. To add monitoring for internal email, contact FortiMail Workspace Security Support [support@perception-point.io]. There may be additional licensing requirements for enabling internal scanning.

  8. Click Enable Google Workspace App - in the bottom right corner. [This is the remediation app.]

    Important: If the Enable Google Workspace App button is not enabled, make sure that you have specified an escalation contact above.

    1. You'll be redirected to a dialog box with instructions, and at the bottom, a place to enter an email address.

      Keep this dialog box open - you'll return to this page later to complete this step, as described below.

    2. In Google Workspace:

      1. Go to your Google Workspace domain's Admin Console.

      2. Click Security > Access and data control > API controls.

      3. Scroll down to the "Domain wide delegation" section, and then select "Manage Domain Wide Delegation".

      4. Click Add new.

      5. Under Client ID, enter 105845669529204264254

      6. Add these scopes to the "0Auth scopes" section:

        1. https://mail.google.com/

        2. https://www.googleapis.com/auth/admin.directory.user.readonly

        3. https://www.googleapis.com/auth/admin.directory.group.readonly

        4. https://www.googleapis.com/auth/admin.directory.domain.readonly

        5. https://www.googleapis.com/auth/apps.licensing

          Note: You can click the Copy to Clipboard icon [] in the "Email Service Configuration" dialog box to copy a comma-delimited list of the required scopes.

      7. Click Authorize.

    3. In FortiMail Workspace Security

      Return to the dialog box in FortiMail Workspace Security that was opened earlier in this procedure:

      1. In the field with the text "Your Email" [at the bottom of the dialog box], enter an admin email address [see the Important note below for details].

        Important:

        • We recommend that you create an email address that is dedicated to this integration only. This will ensure that the email address is always available - and that the integration is not dependent on the continued availability of a specific user in your organization.

        • The email address should have Super Admin privileges [with API permissions].

          An error message similar to "Integration Error: email address may be invalid" may indicate that the specified user [email address] doesn't have the required permissions.

      2. Click Next.

        The "Add a New Service - Protection" dialog box opens.

  9. Specifying who to protect [Google Workspace - API]

    [This is also known as the plan.]

    1. Protect the organization's entire Google Workspace account: Protects all email addresses in all the domains that are included in your organization's Google Workspace account.

      Note: Domains and email addresses that are added in the future to the organization's Google Workspace account will be automatically protected - it is not necessary to make any changes in FortiMail Workspace Security.

    2. Protect the following entities: Allows you to specify which domains and users [email addresses] to protect.

      Note:

      • After onboarding a Google Workspace API integration, you can change the set of assets that are protected by FortiMail Workspace Security. Changing the set of assets includes:

        • deleting any of the specified domains or users

        • specifying additional domains users

        For details, see Editing the protected assets.

      • You can specify a maximum of 300 assets [domains and users] to protect.

      Domains

      Protects the domains that you specify. All users inside the specified domains will be protected.

      Note:

      • Email addresses that are added [in Google Workspace] in the future to any of the specified domains will also be protected.

      • Domains that are added to the organization's Google Workspace account won't be automatically protected. For details, seeAdding a domain to an existing integration.

      [It may take up to 24 hours for a new or modified entity to be added or updated in FortiMail Workspace Security.]

      Users

      Protects all the users that you specify.

      Note:

      • Email addresses that you specify must be included in your Google Workspace account.

      Note about future changes:

      • Domains that are added to your Google Workspace account in the future will not be protected.

      • Email addresses that are added in the future [in Google Workspace] to any of the specified domains will also be protected.

        [It may take up to 24 hours for a new or modified entity to be added or updated in FortiMail Workspace Security.]

      • Email addresses that are added to your Google Workspace account [outside of the specified domains] in the future will not be protected.

  10. Click Next. A summary of your selected configurations will be displayed.

  11. Review the configurations, and then click Done. This will begin the connection process to protect the users that you specified above. This connection process may take a while to complete.

    Note: If spam is not automatically quarantined and end users don't have any contradictory rules in their Google email accounts, emails identified as spam will be delivered to the Spam folder by default. To change the Spam delivery destination, see Configuring the spam remediation destination below.

  12. If you want to configure this Google Workspace integration to operate in monitoring mode, continue with Configuring monitoring mode below.

Configuring monitoring mode

Important: Perform this procedure only if you want your Google Workspace API integration to operate in monitoring mode.

Monitoring mode is typically used for PoC implementations.

In monitoring mode [also known as passive, silent, or detection mode], FortiMail Workspace Security will not:

  • quarantine malicious emails

  • route spam to the Spam folder

To configure the API integration to operate in monitoring mode:

  1. Open the Settings > Bundles and Channels page.

  2. On the right, click Default Channel Settings.

  3. Click Edit [].

  4. Under Detection, clear the Malicious, Restricted, and Spam check boxes.

  5. Click Save.

  6. Open the Settings > Bundles and Channels page.

  7. Under Enabled Channels, on the right of Email Service > Google Workspace, click Email Service Settings. The "Email Service Settings" sidebar opens.

  8. Click Edit [].

  9. Under "Google Account Options" > "Spam destination", select Inbox.

  10. Click Save.

    Your Google Workspace API Integration is now configured to operate in monitoring mode.

    FortiMail Workspace Security will not quarantine any malicious emails or route spam to Spam folders.

Configuring feedback emails [Optional]

By default, the FortiMail Workspace Security IR Team won't send feedback to end-users that report email messages using the Report Message button. However, you can configure FortiMail Workspace Security so that the FortiMail Workspace Security IR Team will send feedback to end-users that report email messages. For details, see Notify requester upon investigation handling.

Adding protected Assets [domains and users]

After you have configured a Google Workspace API integration, you can add domains and users to the list of assets that are protected.

Note: You can add domains and users only if you are protecting just a specified set of assets [partial protection] - and not the entire Google Workspace account. For details, see Full protection vs Partial protection.

To add domains and users to the list of assets that are protected:

  1. In FortiMail Workspace Security, go to Settings > Protected Email Assets.

  2. Click "Configure Email Protection" in the top-right corner. This will open the configuration wizard.

  3. In the wizard, use the available controls to add the required domains and users.

  4. Click Next to continue with the required configuration changes.

Note: You can also click "Add Domains" or "Add Users" on the right of the relevant section. A pane will open on the right - enabling you to add the required assets.

Configuring protected assets [domains and users]

After you have configured a Google Workspace API integration, you can configure [edit] the protected assets, as shown below.

Note: You can configure protected assets only if you are protecting just a specified set of assets [partial protection] - and not the entire Google Workspace account. For details, see Full protection vs Partial protection.

  • Adding assets

To add a domain or user:

  • Click "Add Domains" or "Add Users" on the right of the relevant section. A pane will open on the right - enabling you to add the required assets.

    or

  1. In FortiMail Workspace Security, go to Settings > Protected Email Assets.

  2. Click "Configure Email Protection" in the top-right corner. This will open the configuration wizard.

  3. In the wizard, use the available controls to add the required domains and users.

  4. Click Next to continue with the required configuration changes.

  • Enabling assets

  • Disabling assets

  • Deleting assets

You can use the functionality on the Protected Email Assets page to enable, disable, or delete any of the protected assets [domains and users].

The required controls are found on the right of each protected asset.

Configuring the spam remediation destination

Configuring a Google Workspace API integration includes specifying what happens to emails that are assigned a spam verdict [if spam emails are not configured to be quarantined]. The options are:

  • Inbox: The email is sent to the user's Inbox. This setting is typically used for PoC installations - not for production installations.

  • Junk: The email is sent to the user's Spam folder. This setting is typically used in production installations - not in PoC installations.

With the Google Workspace API integration, FortiMail Workspace Security may move an email from the Inbox to the Spam folder after the email has initially arrived in the Inbox. The procedure is therefore referred to as "spam remediation".

When a Google Workspace API inbound integration is initially configured, the spam remediation destination is set to Junk.

Note: The "spam remediation" functionality will apply only if:

  • There are no contradictory rules in the Google email account. For details, contact FortiMail Workspace Security Support [support@perception-point.io].

  • Spam emails are not configured to be quarantined. If Spam emails are configured to be quarantined, then Spam emails will be sent to quarantine, and not sent to the Spam folder or the Inbox. For details, see Which verdicts cause quarantine.

Important: The spam remediation controls are functional only if a Google Workspace API inbound integration is configured. The controls are NOT functional if a Google Workspace Inline integration is configured.

To change the spam remediation destination:

  1. Open the Settings > Bundles and Channels page.

  2. Under Enabled Channels, on the right of Email Service > Google Workspace, click Email Service Settings.

    The "Email Service Settings" sidebar opens.

    Note: The "Spam destination" functionality is applicable to Google Workspace API integrations only - not to Google Workspace Inline integrations.

  3. Click Edit [].

  4. Under "Google Account Options" > "Spam destination", select Junk or Inbox.

  5. Click Save.

Automatic calendar events

Scenario

  • You have a Google Workspace integration.

  • An email is determined to be malicious - and is quarantined.

  • The email includes a calendar event - typically as a .ics attachment.

Results

  • The event is automatically added to the user's calendar. This occurs as soon as the email reaches the Google Workspace servers - before the email is scanned by FortiMail Workspace Security.

  • FortiMail Workspace Security is unable to delete the event from the calendar.

Workaround

To stop Google from automatically adding invitations or events from emails, an administrator can perform the following configuration - for everyone in the organization (or for specific departments/teams):

  1. Sign in to the Google Admin Console.

  2. Go to Menu > Apps > Google Workspace > Calendar.

  3. Click on Advanced Settings.

  4. (Optional) If you want to change this for a specific team only, select the Organizational Unit (OU) or Group from the list on the left.

  5. Find the section labeled "Add invitations to calendar".

  6. Select one of the following options:

    • Invitations users have responded to via email: This is the more restrictive and cleaner option.

    • Invitations from known senders: This allows invites from colleagues or people in their contacts but blocks strangers.

  1. Click Save.

To stop Google from automatically adding invitations or events from emails, end-users can perform the following configuration:

  1. Open Google Calendar in your Chrome browser.

  2. Click the Gear icon (Settings) in the top right and select Settings.

  3. In the left-hand sidebar, click on General > Event settings.

  4. Find the setting labeled "Add invitations to my calendar."

  5. Change the dropdown to either:

    • Only if the sender is known

      - or -

    • When I respond to the invitation in email

      Note: This ensures that an event only shows up once you’ve clicked "Yes" or "Maybe" in the actual email.

See also: