IMPORTANT: Hoxhunt has released a new Google Workspace Add-in for Gmail, which is the
recommended option for all new Hoxhunt customers. Read more:
Hoxhunt button: Distributed installation of the Google Workspace add-on
Please reach out to your Onboarding Manager before continuing with the installation
of the Native Gmail add-on.
Hoxhunt for Gmail add-on is not yet generally available through Google Marketplace. However, Hoxhunt's native Gmail add-on can be implemented as a Private Gmail App for the time being.
If you are interested in the Chrome implementation, please check this article.
Requirements for implementation
User with Google Administrator rights is needed to complete the setup
User must have basic knowledge and skills to operate in Google Admin Console
User must have access to Google Cloud Projects at https://console.cloud.google.com/.
Separate whitelisting in G Suite must be implemented before or after implementing the Private Gmail add-on. This allows Hoxhunt simulations to arrive safely and that they can be reported successfully.
Gmail might prevent you from reporting certain type of suspicious emails. This is a technical security restriction and it cannot be currently controlled by Hoxhunt or G Suite Admins.
- These instructions expect you to use the Legacy Editor when accessing the two Hoxhunt projects via https://script.google.com/
Pre-task: Whitelist incoming Hoxhunt emails
A) Receive shared Google Cloud Projects
- Navigate to https://script.google.com/
- Switch to Shared with me folder and locate both Hoxhunt addon loader and Hoxhunt for Gmail.
- Click on Hoxhunt addon loader.
- Select File > Make a copy.
IMPORTANT: Your editor view should look like this:
If the layout doesn't match the instructions, please switch to the Legacy Editor.
B) Set up a new Cloud Platform Project
Next to the main title Google Cloud Platform, click Select a Project > Select from [organization name] > NEW PROJECT.
Provide your new project a name Hoxhunt for Gmail and click CREATE.
Navigate to APIs & Services > OAuth consent screen.
TIP: If you are unable to locate it, user Search bar and look for "OAuth consent screen".
In the OAuth consent screen section, tick Internal and click CREATE.
Fill in data as follows:
App name: Hoxhunt for Gmail
User support email: email@example.com or your own internal support address
Application logo: Logo_shield.png (downloadable at the end of this article)
Application homepage link: https://www.hoxhunt.com/
Application Terms of Service link (Optional): leave empty
Authorised domains: hoxhunt.com
Developer contact information: firstname.lastname@example.org
Click SAVE AND CONTINUE.
- In the Scopes section, click ADD OR REMOVE SCOPES.
- Scroll down to Manually add scopes, and paste in the following lines:
- click ADD TO TABLE and then click UPDATE.
- Click SAVE AND CONTINUE. No actions are needed on the Summary page.
C) Link Hoxhunt addon loader to your new Cloud Platform Project
- Click on Google Cloud Platform title at the top blue bar.
- Make a note of the Project number visible under Project info section.
- Switch back to your Copy of Hoxhunt addon loader tab and link it to your Cloud project by selecting Resources > Cloud Platform Project…
- Enter your Project number and click Set Project.
- Click Confirm and Close.
D) Enable private Hoxhunt for Gmail add-on
While you have Copy of Hoxhunt addon loader open, select Publish > Deploy as add-on…
If prompted, Click Accept. Publish an add-on dialog will appear.
Instead of clicking Ok, click on G Suite Marketplace SDK link in the dialog.
(You will be taken to Google Cloud Platform > APIs & Services > Dashboard > Google Workspace Marketplace SDK)
In the navigation side bar, switch to App Configuration section.
Under App integration, tick Google Workspace add-on checkbox. Deployment ID field will appear.
Switch back to Copy of Hoxhunt addon loader tab.
Select Publish > Deploy from manifest…
Deployments dialog opens. Click Create. Fill in the following details:
Deployment name: Hoxhunt for Gmail (MM-DD-YYYY)
In Deployments dialog, click Get ID next to Hoxhunt for Gmail (MM-DD-YYYY).
Copy-paste the Deployment ID back to Deployment ID field.
(Google Workspace Marketplace SDK > App Configuration > App integration > Google Workspace add-on)
Warning: Do not click SAVE until you have completed step 16! App visibility setting will be otherwise locked and if you had it in wrong setting, you need to restart the implementation.
Scroll down to Developer Links and fill in the following details:Application website URL: https://app.hoxhunt.com/
Developer name: Hoxhunt Oy
Developer website URL: https://www.hoxhunt.com/
Developer email: email@example.com
- Scroll down to Installation Settings and choose how Hoxhunt can be installed:
Individual + Admin install (users are able to install Hoxhunt add-on on their own)
Admin-only install (only Admins can control the installation)
- Scroll down to App Visibility and tick Private.
Warning: Once you choose an app visibility option and save the App Configuration page, you can't change your selection later.
- Click Save.
Switch to Store listing section.
Under App Details, click on downward pointing arrow and enter following details:
Application name: Hoxhunt for Gmail
Short Description: Hoxhunt is an automated cyber training program that transforms the way your employees react and respond to the growing amount of phishing emails.
Detailed Description: Hoxhunt is an automated cyber training program that transforms the way your employees react and respond to the growing amount of phishing emails.
Set Category to Utilities.
Scroll down to Graphics Assets and upload Application Icons and Screenshots from the materials package (downloadable at the end of this article):Application icons: icon_32x32.png, icon_48x48.png, icon_96x96.png, icon_128x128.png
Application Card Banner: Banner_220x140.png
Screenshots: 1_Stars.png, 2_User-dashboard.png, 3_Invitation start.png, 4_Onboarding 1.png, 5_Onboarding 2.png
- Scroll down to Support Links and fill in the data as follows:
Terms of service URL: https://www.hoxhunt.com/
Setup URL: leave empty
Admin config URL: leave empty
Support URL: https://support.hoxhunt.com/
Deletion policy URL: leave empty
Help URL: https://support.hoxhunt.com/
Report issue URL: leave empty
- Under Distribution, tick All regions.
- Click Publish.
Congratulations! Hoxhunt is now available in your domain's Marketplace.
E) Distribute Hoxhunt for Gmail add-on
Navigate to https://admin.google.com and select Apps > Google Workspace Marketplace Apps.
At the top of the list, click Add app to domain install list.
TIP: you can also go directly to https://gsuite.google.com/marketplace/mydomainapps
Search for “Hoxhunt” and click on Hoxhunt for Gmail.
Click Domain install.
- Under Domain wide install dialog and click CONTINUE. Then select Turn ON for and select the OUs (operational units) you wish to install Hoxhunt add-on to, agree the terms and click ALLOW.
Hoxhunt for Gmail has now been installed!
Switch back to admin.google.com and navigate to Apps > Google Workspace Marketplace Apps. If you can’t see Hoxhunt for Gmail on the list yet, refresh the page.
TIP: If you want to change the availability scope afterwards, go to https://admin.google.com/ac/apps/gmail/marketplace/domaininstall, click Hoxhunt for Gmail and then select the Organisational units you want Hoxhunt add-on to be installed.
F) Test your private Hoxhunt for Gmail add-on
Log in to Gmail.
Open any email and click Hoxhunt button visible on the right-hand side.
TIP: Make sure you have Side panel open.
On first time, Hoxhunt for Gmail add-on will ask for authorisation to access your email.
Click AUTHORIZE ACCESS and enter your credentials.
Click REPORT and follow given instructions.
This concludes the implementation!
Removing private Hoxhunt Gmail App
A) Disable private Hoxhunt Gmail App’s for all users
Go to admin.google.com and navigate to Apps > G Suite Marketplace apps.
Click Hoxhunt for Gmail in the apps list, select OFF for everyone and click SAVE.
Private Hoxhunt Gmail App is now uninstalled from all users.
B) Remove Hoxhunt for Gmail Cloud Project
Go to console.cloud.google.com and you'll land on Dashboard/Home view.
Click Hoxhunt for Gmail at the top-most blue bar.
Click the kebab menu in the top-right corner and select Manage resources > Hoxhunt for Gmail and click DELETE.
Enter the Project ID visible in the underlying view (“Hoxhunt for Gmail”) and click Shut down to complete removal.
Cloud Project will be removed by Google in the coming weeks.
C) Remove copy of Hoxhunt add-on loader
Navigate to Google Drive.
Remove your copy of Hoxhunt addon loader.
Hoxhunt will stop sharing Hoxhunt for Gmail and Hoxhunt addon loader in a moment.