Hoxhunt button: Special - Install and test a private Google Workspace add-on with custom logo

Introduction

These instructions are for customers who require their Hoxhunt add-on to be personalized.

Custom or white labeled Hoxhunt add-ons are available per separate agreement to select customers. If you are unsure whether or not your agreement includes a custom or white labelled add-on, please reach out to your Onboarding Manager or Customer Success Manager.

For organizations that require their custom logo on the add-on, the installation process is significantly longer. This process is covered step-by-step in this document.

NOTE: The regular Hoxhunt Google Workspace add-on is available from the Google Workspace Marketplace. Customers are recommended to install the official Google Workspace add-on and use it as-is. Read more: Hoxhunt button: Introduction to the Hoxhunt Google Workspace add-on and Hoxhunt button: Distributed installation of the Google Workspace add-on

UPDATE October 7th, 2025:
The implementation process has changed and this article has been updated accordingly. If you have deployed your custom Google Workspace add-on before October 7th, 2025, you don't need to re-do the whole implementation. Instead, you can just switch from Apps Script-based deployment to HTTP-based deployment.

 

Before you start

  • Contact your Onboarding Manager or Customer Success Manager or support@hoxhunt.com to gain access to the code projects required for the installation.
  • Make sure you have your custom logo assets available.
  • Google Administrator rights are needed to complete the setup. Make sure you have administrative access to your organization's Google Workspace.
  • You must have basic knowledge and skills to operate in Google Admin Console.
  • You must have access to Google Cloud Projects at https://console.cloud.google.com/.
  • You must have permission to create and manage a new Google Cloud Platform (GCP) project.

 

Disclaimers

  • Support from Hoxhunt to assist with installation and maintenance of the privately hosted add-on is not necessarily included as a part of your service agreement. Please be in contact with your Customer Success Manager for more information.
  • Separate configuration of Gmail API Delivery must be implemented before or after implementing the privately hosted Hoxhunt add-on. This allows Hoxhunt simulations to be delivered reliably and that they can be reported successfully.

 

A) Create a new Google Cloud Platform (GCP) project

  1. Go to https://console.cloud.google.com.
     
  2. Type "create a project" into the top search box.
     
  3. Choose Create a Project - IAM and admin from the search results.
     
  4. In the New Project view:
    1. To Project name field, enter a suitable project name, such as "Hoxhunt for Gmail".
    2. In Organization field, ensure correct organization is selected.
    3. In Location field, choose a location for your project.
    4. Click CREATE.
       
  5. Wait for your new project to be created in the Notifications pop-up window. This should only take a few seconds.
     
  6. In the Notifications pop-up, click SELECT PROJECT. (Alternatively, choose your newly created project from the Projects list next to the main title Google Cloud Platform on the top bar.)
     
  7. Make a note of the Project number shown in the Project info section - it will be needed later.

IMPORTANT: It's strongly recommended that you add other administrators as co-owners to the GCP project. If you don't, if your Google Workspace account ever gets suspended or deleted, the add-on's installation will become inoperable and you need to re-do the implementation from scratch.

 

B) Configure your Google Cloud Platform (GCP) project

  1. Navigate to https://console.cloud.google.com.
  2. Make sure you have selected your project from the blue top bar.
     

Enable Gmail API

  1. Type "gmail api" into the top search box.
    Choose Gmail API - Google Enterprise API from the search results.
     
  2. Click Enable.
    NOTE: If Gmail API is already enabled, no action needs to be taken here.
     

OAuth Consent Screen

Basic settings

  1. Type "oauth consent screen" into the top search box.
    Choose OAuth consent screen from the search results.
     
  2. Select the Internal option.
     
  3. Click Create.
     

  4. Under App Information, enter "Hoxhunt for Gmail". This name will be used when permission consent is requested from the user on the OAuth consent screen upon first use.

    NOTE: If the add-on is installed by an administrator to a group of users, the consent screen will never be shown for those users. The installing administrator provides consent on behalf of all the users.
     

  5. Select a support email address from the list.
    The list contains your email address and a list of groups you manage in the Google Admin Console.
     
  6. Under the App domain > Authorized domains section, click Add domain.
    Enter hoxhunt.com into the text box that appears.
     
  7. Under Developer contact information, enter appropriate contact email address.
    This email address is for contacts regarding this specific installation of the add-on. As such, you should not enter any @hoxhunt.com address here, but an address that reaches your organization's Google administrators. The email address may be used if Google needs to contact an administrator of the add-on.
     
  8. Click Save and continue.

Scopes

  1. Click Add or remove scopes.
     

  2. Into the Manually add scopes text field, insert the following URLs:

    https://www.googleapis.com/auth/gmail.addons.current.message.metadata https://www.googleapis.com/auth/gmail.addons.current.message.readonly https://www.googleapis.com/auth/gmail.addons.execute
    https://www.googleapis.com/auth/gmail.modify
    https://www.googleapis.com/auth/userinfo.email
     
  3. Click Add to table.
    The table should be populated with six selected rows (and potentially some unselected ones).
     
  4. Click Update.
     
  5. Click Save and continue.
     
  6. Click Back to dashboard.

Enable Google Workspace Marketplace API

  1. Type "marketplace sdk" into the top search box.
    Choose Google Workspace Marketplace SDK from the search results.
     
  2. If Google Workspace Marketplace SDK settings are accessed for the first time, the API needs to be enabled by clicking Enable. If you see a button that says Manage instead, move to the next step.
     

C) Set up and customize your Hoxhunt add-on

Create a custom http deployment (alternate runtimes) pointing to Hoxhunt 

  1. Click “manage” on the Google Workspace Marketplace SDK page.

  2. From the navigation tabs, select “http deployments” tab.

  3. Select “Create new deployment”.

  4. Type an ID for the deployment, e.g “Custom Hoxhunt Google Workspace Add-on Deployment”.

  5. Input the deployment.json file attached to the end of this article into the “deployment.json” textbox.

  6. To customize the add-on icon (button), provide a URL to the custom image file to “logoUrl”. The resource image should be 64x64px in dimension.

  7. To customize the name of the add-on (button), modify the value of “name”.

 

D) Configure and publish Google Marketplace store listing for Hoxhunt add-on

  1. Type "marketplace sdk" into the top search box.
    Choose Google Workspace Marketplace SDK from the search results.
     
  2. Click Manage.
    You will end up in the Credentials section in Google Workspace Marketplace SDK > Enabled APIs and services.

App configuration

  1. Next to Credentials tab, switch to App configuration tab.
    WARNING! Do NOT click the "Save" button before changing the "App Visibility" setting to Private. If you do, you will have to start the entire installation process from scratch.
     
  2. In the App Visibility section, choose Private.
    WARNING! This selection is final! It can not be changed after Save is clicked. Only way to change this setting is to re-create the GCP project and start from scratch.
     
  3. In the Installation Settings section, choose an option suitable to you:
    • Individual + Admin install (any user in your organization can install/remove the add-on for themselves)
    • Admin-only install (only Admins can install/remove the add-on) <- Recommended option for most
       
  4. Under App integration section, enable the Google Workspace add-on option.
     
  5. Choose HTTP or other deployments.
     
  6. Select the Deployment with the ID you created in the previous step C).
     
  7. Remove all existing Scope fields (hover over to reveal a trash can icon).
     
  8. Create six (6) new fields by clicking Add scope button.
     
  9. Enter the following URLs to each Scope field: https://www.googleapis.com/auth/gmail.addons.current.message.metadata
    https://www.googleapis.com/auth/gmail.addons.current.message.readonly
    https://www.googleapis.com/auth/gmail.addons.execute
    https://www.googleapis.com/auth/gmail.modify
    https://www.googleapis.com/auth/userinfo.email
     
  10. Fill in the developer links as follows:
    Developer name: Hoxhunt Oy
    Developer website URL: https://www.hoxhunt.com/
    Developer email: support@hoxhunt.com
     
  11. Double-check and make sure App Visibility is set to Private.
     
  12. Click Save.
     

Store listing

  1. Scroll back up, and switch to Store listing tab.
     
  2. Under App Details section, click the arrow pointing downwards next to the default language selection.
     
  3. Enter the 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.

     
  4. Click Done.
     
  5. Select Category: Utilities.
  6. In the Graphics Assets section, upload Application Icons and Screenshots from the materials package (downloadable at the end of this article).
    TIP: For Application icons, you can use your custom Hoxhunt button logo to keep the store listing visually consistent with the actual button in Gmail.

    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

     
  7. In the Support Links section, enter the following information:
    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--
     
  8. In the Distribution section, select All Regions.
     
  9. Click Save.
     
  10. Finally, click Publish.
    NOTE: If the Publish button is greyed out, some of the required information has not been entered correctly. Double-check that:
    • You've correctly entered the Deployment ID in App configuration section.
    • You've correctly entered all other details in App configuration and Store listing sections.
       
  11. Once published, make a note of the App URL shown at the top of the Store listing view.
     

E) Provide Google Workspace Client ID to Hoxhunt

As you are implementing a private Google Workspace Marketplace add-on, Hoxhunt needs to explicitly allow your Deployment Authorization Client ID before the add-on's calls to Hoxhunt backend are allowed. Please follow the steps below to provide the Client ID to Hoxhunt.

IMPORTANT: If you don't provide Client ID to Hoxhunt, you will get the following error message when using Hoxhunt add-on: Error creating invocation context. 401: Unauthorized

  1. Navigate to https://console.cloud.google.com/
  2. Make sure you have the correct Cloud Project selected at the blue top bar (for example Hoxhunt for Gmail).
  3. In the Welcome view, select APIs and services (under Quick access).
  4. From the right-hand side navigation, select Credentials section.
  5. Under OAuth 2.0 Client IDs, locate Google Workspace Add-ons row and copy the Client ID value.
    TIP: You can also obtain the same Client ID value by switching to HTTP Deployments tab. Under Authorization Resource, copy the OAuth Client Id value.
  6. Provide Hoxhunt with the copied value. You can email it to support@hoxhunt.com. Please mention that this is for a custom Google Workspace add-on.
  7. After Hoxhunt has confirmed the Client ID has been configured in the backend, you can proceed with the implementation.

 

F) Install the Hoxhunt add-on for users

  1. Navigate to the App URL you wrote down after publishing the add-on to the Google Workspace Marketplace store.
     
  2. Different buttons will be available depending on your selection back in Installation Settings. Click the appropriate Install button.
     
  3. Click Continue at the first prompt.
     
  4. Choose whether you want to install the add-on only to specific users or to everyone.
    • If you initially choose to install the add-on only for a few users, you can change the user scope later through the Google Workspace Admin Console.
    • If you chose to only install for some users, you can select the desired users after clicking Next.
       
  5. Finally, click Finish to complete the installation.
     

Congratulations! This concludes the installation steps.


According to Google, it may take up to 24 hours for new add-ons to appear to all users, but often times it happens almost right away. The Hoxhunt for Gmail add-on with your custom logo will eventually appear in Gmail for the designated users. To speed up the process, you can ask employees to refresh their Gmail page or close and relaunch Gmail app on their mobile device.

 

APPENDIX

Changing the installation scope

1. Go to https://admin.google.com/ac/apps/gmail/marketplace/domaininstall

2. Click Hoxhunt for Gmail in the apps list.

3. Under User access, select View organisational users and groups. 

4. On the left-hand side, change the scope as appropriate.

Disabling the add-on temporarily

1. Go to https://admin.google.com/ac/apps/gmail/marketplace/domaininstall

2. Click Hoxhunt for Gmail in the apps list.

3. Under User access, select View organisational users and groups. 

4. Under App distribution, select OFF for everyone.

 

Permanently remove Hoxhunt's private Google Workspace add-on

1. Delete the add-on

  1. Go to https://admin.google.com/ac/apps/gmail/marketplace/domaininstall
  2. Click Hoxhunt for Gmail in the apps list.
  3. On the left-hand side, select DELETE APP.

Hoxhunt's Google Workspace add-on is now uninstalled from all users.

 

2. Remove the associated Google Cloud Platform project

  1. Go to https://console.cloud.google.com/ and you'll land on Dashboard/Home view.
  2. Make sure you have your Hoxhunt for Gmail project selected at the top-most blue bar.
  3. Click the kebab menu in the top-right corner and select Project settings.
  4. Select SHUT DOWN.
  5. To verify your action, enter the Project ID visible in the underlying view (“Hoxhunt for Gmail”) and click Shut down to complete the project shut down.

Once shut down, your Hoxhunt for Gmail cloud project will be removed by Google automatically in the coming weeks.

 

3. Remove copy of Hoxhunt add-on loader

NOTE: This step is only valid for customers who were still using separate Apps Script-based custom Hoxhunt Google Workspace add-on at the time removing their Hoxhunt add-on.

Navigate to Google Drive > My Drive.

  1. Remove your copy of Hoxhunt addon loader.

Hoxhunt will stop sharing the original Hoxhunt add-on loader and Hoxhunt add-on loader template visible under Shared with me after a while.

Was this article helpful?

3 out of 3 found this helpful

Have more questions? Submit a request