Introduction

Gmail conducts scanning and classification of emails received as a part of their Advanced phishing and malware protection. When simulated threats are sent using traditional methods, e.g. sending them via email with the Hoxhunt IP’s allowlisted, there’s a risk that the simulated threats:

• are not received by the end user at all

• are marked as “failed” due to Gmail’s actions, causing false positives

• are received with the Google warning banner, preventing the user from reporting the email with the Hoxhunt button

• trigger an auto-response, such as out-of-office replies, which generate a stream of error messages into user's mailbox causing inconvenience

• trigger auto-forward rules which might forward simulations to users who were not meant to receive them, typically causing technical issues and ambiguity

While the problems could be mitigated by deny listing simulations that are causing these problems, this limits the training capabilities and can impact the quality of the Hoxhunt training.

Hoxhunt Gmail API Delivery

To overcome the challenges outlined above, Hoxhunt supports simulation delivery using the Gmail API, which is the default recommended delivery method of simulated threats by Google. The delivery method bypasses most scanning and classification done by Google, thus making it possible to deliver as wide variety of simulations as possible, increasing the quality and scope of the Hoxhunt training.

Simulation delivery via the Gmail API suppresses both autoresponders as well as auto-forwarders. The end result is that the user receiving the simulated threat delivered via the Gmail API doesn’t give out a hint that the message might be malicious.

The experience of receiving a simulation delivered through the Gmail API is more realistic, as the user has less warnings, and thus, needs to detect the warning signs themselves. In the future simulation delivery using the Gmail API allows Hoxhunt to teach users even more realistic attack scenarios, such as account compromises.

While the above benefits themselves would solely give merit to using the simulation delivery using Gmail API, the setup also requires less effort compared to setting up the traditional email delivery through IP allow/whitelisting.

How does email delivery through the Gmail API work?

When using Gmail API Delivery, Hoxhunt directly inserts simulations into users' mailboxes in a similar manner to IMAP APPEND, bypassing most scanning and classification done by Google. This means that Hoxhunt actually does not send a traditional email, but rather delivers it via a call against the Google API. You may read the technical details of the actual request from Google’s API documentation here: https://developers.google.com/gmail/api/reference/rest/v1/users.messages/insert.

OAUTH 2.0 protocol is used for authentication and authorization. Hoxhunt obtains OAuth 2.0 client credentials from Google. Then Hoxhunt requests an access token from the Google Authorization Server, and sends a request against Google API using the token for authorization. You can read more how OAUTH 2.0 works in Google's documentation here: https://developers.google.com/identity/protocols/oauth2/

Authorization against the Google API for delivering simulations utilizes scopes. The Gmail API Delivery requires the https://www.googleapis.com/auth/gmail.insert scope. This grants Hoxhunt access to insert messages into a user's inbox. You can read more about scopes here: https://developers.google.com/identity/protocols/oauth2/scopes#gmail

How to setup the Gmail API Delivery

Before you start

Before you start configuring the Gmail API Delivery for Hoxhunt, make sure you meet the following technical requirements:

• you have a Gmail account with Admin access

• you have Admin access to Hoxhunt in order to gather necessary setup information (if you don't have access, please reach out to your Onboarding Manager or Customer Success Manager)

Setup steps

1. Go to https://admin.hoxhunt.com/settings/email-delivery

2. Click the link or open https://admin.google.com/u/2/ac/owl/domainwidedelegation in another browser window/tab. The following page should appear.

3. Click Add new link to create a new link and copy-paste the client ID and the scope from https://admin.hoxhunt.com/settings/email-delivery.

4. Click authorize and return to https://admin.hoxhunt.com/settings/email-delivery

5. Enable simulation delivery using Gmail API using the toggle as depicted in the screenshot below in https://admin.hoxhunt.com/settings/email-delivery

Audit trail

Google provides extensive capabilities for logging simulated threat delivery using the Gmail API. Logging can be accessed through the Google Admin console’s Reporting → Audit → Token view or directly using the following link: https://admin.google.com/ac/reporting/audit/token

You can find all events affiliated with simulated threat delivery using the Gmail API by filtering the Audit Log based on the client ID. You can obtain the client ID from https://admin.hoxhunt.com/settings/email-delivery. It’s possible to do very fine-grained filtering using the filtering capabilities provided by Google. Additionally, alerts can be set up based on the filters.

Questions and Answers

Q: I’m an existing customer using Gmail environment, how can I set this up?

A: Contact your Customer Success Manager and we can gladly assist you in the setup.

Q: Will Hoxhunt be able to read my employees emails with the Gmail API Delivery?

A: No, Simulation delivery using Gmail API has strictly limited permissions. The only thing that Hoxhunt is allowed to do is to insert a message into user's mailbox.

Q: Is Hoxhunt able to make any changes to my email environment using the Gmail API Delivery?

A: No, Simulation delivery using Gmail API has strictly limited permissions. The only thing that Hoxhunt is allowed to do is to insert a message into user's mailbox.

Q: Does Gmail API delivery require domain-wide delegation to work?

A: Yes.

Q: I receive the following error when I try to enable Gmail API Delivery in Hoxhunt Admin Portal.

Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.

A1: The toggle makes a connection attempt to your Gmail API. If you haven’t completed the domain-wide delegation on your side, this error occurs. Please complete the configuration in your Google Workspace and try again. Also note it might take a few minutes before the domain-wide delegation takes effect on Google's side.

A2: Please verify that you're logged in to the Hoxhunt admin portal with an account/email address that exists for the tenant you're activating the API delivery for.

I still have questions?

If you have any other questions, please just reach out to your Hoxhunt Onboarding Manager, Customer Success Manager or support at support@hoxhunt.com