Hoxhunt button: Special - Distributed installation of Hoxhunt for Google Workspace (native Gmail add-on)

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.

Introduction

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/.

Disclaimers

• Separate whitelisting in Google Workspace 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 Google Workspace Admins.

• These instructions expect you to use the Legacy Editor when accessing the two Hoxhunt projects via https://script.google.com/

Summary

Pre-task: Whitelist incoming Hoxhunt emails

A) Receive shared Google Cloud Projects

B) Set up a new Cloud Platform Project

C) Link Hoxhunt addon loader to your new Cloud Platform Project

D) Enable private Hoxhunt for Gmail add-on

E) Distribute Hoxhunt for Gmail add-on

F) Test your private Hoxhunt for Gmail add-on

A) Receive shared Google Cloud Projects

B) Set up a new Cloud Platform Project

1. Go to https://console.cloud.google.com.

2. Next to the main title Google Cloud Platform, click Select a Project > Select from [organization name] > NEW PROJECT.

3. Provide your new project a name Hoxhunt for Gmail and click CREATE.
   
   

4. Navigate to APIs & Services > OAuth consent screen.
   TIP: If you are unable to locate it, user Search bar and look for "OAuth consent screen".
   
   

5. In the OAuth consent screen section, tick Internal and click CREATE.

6. Fill in data as follows:
   
   App name: Hoxhunt for Gmail
   User support email: support@hoxhunt.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 Privacy Policy link: https://www.hoxhunt.com/
   Application Terms of Service link (Optional): leave empty
   
   Authorised domains: hoxhunt.com
   
   Developer contact information: support@hoxhunt.com

7. Click SAVE AND CONTINUE.
   
   

8. In the Scopes section, click ADD OR REMOVE SCOPES.
9. Scroll down to Manually add scopes, and paste in the following lines:
   https://www.googleapis.com/auth/gmail.addons.execute
   https://www.googleapis.com/auth/gmail.addons.current.message.readonly
   https://www.googleapis.com/auth/userinfo.email
   https://www.googleapis.com/auth/script.external_request
   https://www.googleapis.com/auth/script.send_mail
   
   
10. click ADD TO TABLE and then click UPDATE.
11. Click SAVE AND CONTINUE. No actions are needed on the Summary page.

C) Link Hoxhunt addon loader to your new Cloud Platform Project

1. Click on Google Cloud Platform title at the top blue bar.
2. Make a note of the Project number visible under Project info section.
   
   
3. Switch back to your Copy of Hoxhunt addon loader tab and link it to your Cloud project by selecting Resources > Cloud Platform Project…
4. Enter your Project number and click Set Project.
5. Click Confirm and Close.

D) Enable private Hoxhunt for Gmail add-on

1. While you have Copy of Hoxhunt addon loader open, select Publish > Deploy as add-on…

2. If prompted, Click Accept. Publish an add-on dialog will appear.

3. Instead of clicking Ok, click on Google Workspace Marketplace SDK link in the dialog.
   (You will be taken to Google Cloud Platform > APIs & Services > Dashboard > Google Workspace Marketplace SDK)

4. Click ENABLE.
   
   

5. In the navigation side bar, switch to App Configuration section.

6. Under App integration, tick Google Workspace add-on checkbox. Deployment ID field will appear.
   
   

7. Switch back to Copy of Hoxhunt addon loader tab.

8. Select Publish > Deploy from manifest…

9. Deployments dialog opens. Click Create. Fill in the following details:
   Deployment name: Hoxhunt for Gmail (MM-DD-YYYY)

10. Click Save.

11. In Deployments dialog, click Get ID next to Hoxhunt for Gmail (MM-DD-YYYY).
    
    

12. 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.
    
    

13. 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: support@hoxhunt.com
    
    
14. 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)
    
    
15. 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.
    
    
16. Click Save.
    
    

17. Switch to Store listing section.

18. Under App Details, click on downward pointing arrow and enter following details:
    Language: English
    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.

19. Click DONE.
    
    

20. Set Category to Utilities.
    
    

21. 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
    
    
22. Scroll down to Support Links and fill in the data as follows:
    Terms of service URL: https://www.hoxhunt.com/
    Privacy policy 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
    
    
23. Under Distribution, tick All regions.
    
    
24. Click Publish.

Hoxhunt is now available in your domain's Marketplace.

E) Distribute Hoxhunt for Gmail add-on

1. Navigate to https://admin.google.com and select Apps > Google Workspace Marketplace Apps.

2. 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
   
   

3. Search for “Hoxhunt” and click on Hoxhunt for Gmail.

4. Click Domain install.

5. 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.
   
   

6. 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

1. Log in to Gmail.

2. Open any email and click Hoxhunt button visible on the right-hand side.
   TIP: Make sure you have Side panel open.

3. On first time, Hoxhunt for Gmail add-on will ask for authorization to access your email.

4. Click AUTHORIZE ACCESS and enter your credentials.

5. 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

1. Go to admin.google.com and navigate to Apps > Google Workspace Marketplace apps.

2. 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

1. Go to console.cloud.google.com and you'll land on Dashboard/Home view.

2. Click Hoxhunt for Gmail at the top-most blue bar.

3. Click the kebab menu in the top-right corner and select Manage resources > Hoxhunt for Gmail and click DELETE.

4. 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

1. Navigate to Google Drive.

2. Remove your copy of Hoxhunt addon loader.

Hoxhunt will stop sharing Hoxhunt for Gmail and Hoxhunt addon loader in a moment.

• gmail_material_package.zip900 KB