Please read - Important information regarding the functionality of your Hoxhunt add-in!
| DEADLINE POSTPONED BY MICROSOFT: The deadline for REST API deprecation has been postponed by Microsoft for active add-ins until October 14th 2025. Hoxhunt recommends updating the add-in to take advantage of all functionalities available to our customers. |
Outlook REST API will be deprecated and replaced by Microsoft Graph API. Please take the necessary steps to update your Hoxhunt Outlook add-in by the end of November 2022.
NOTE: If you have deployed Hoxhunt add-in as a stand-alone Outlook COM add-in, this update doesn't apply to you. Learn how to identify your Hoxhunt add-in type here.
Introduction
Hoxhunt’s modern Outlook add-in* uses two distinct APIs to communicate with your Exchange service - Outlook REST 2.0 API and EWS API.
NOTE: If you have deployed Hoxhunt add-in as a stand-alone Outlook COM add-in, this update doesn't apply to you. Learn how to identify your Hoxhunt add-in type here.
For Exchange Online customers, REST API has been used as the primary API, and EWS API as a fallback for example in Hybrid Exchange and delegate (shared mailbox) scenarios. For customers with on-premise Exchange Servers, EWS API has been used as the only API.
In late 2020, Microsoft announced they would deprecate Outlook REST 2.0 API in favor of Microsoft Graph API by November 30th, 2022.
After the change, Exchange Online customers will be using Graph API as the primary API and EWS API as a fallback method (for example in Hybrid and delegate scenarios). Although there will be no visible changes for customers with on-premise Exchange Servers, Hoxhunt strongly recommends to update your add-in in any case.
To ensure our customers with a smooth transition to Microsoft Graph API we now ask all our customers to approve the usage of the Microsoft Graph API by updating the add-in before the November deadline.
NOTE: Even though Hoxhunt has the technical means to identify when your organization starts emitting Graph API calls, please let us know once you have completed the configuration.
Please update your Hoxhunt Outlook add-in to latest version 1.0.0.7 by the end of November 2022 by following the instructions further below.
Move over to Microsoft Graph API with your Hoxhunt add-in
Most new features in Hoxhunt can be enabled and disabled without updating the add-in itself. However, in order to move over to Graph API you will need to consent to the new Graph API permissions.
1. Please follow the instructions at this page to update the add-in.
2. A view with permissions and capabilities will be shown when you update the add-in. Please review the permissions and click Save.
Frequently asked questions
How soon can we expect the updated add-in to reach our users?
Microsoft doesn't disclose any specific timeline, since the update is done gradually across all target users. Restarting Outlook client may speed up the process. Based on our experience, it can take up to a few days until the update is completed to all users.
Are there any notable changes with the introduction of Graph API?
There will be no visible changes to the end user facing functionality of the Hoxhunt Outlook add-in. However, Microsoft Graph API comes with few improvements over Outlook REST 2.0 API. For example, add-in's permissions will be more visible through scopes, the API provides access to a MIME representation of user's reported email message, and it also allows batching multiple API requests into one HTTP request allowing future optimizations.
Could you explain the permission model of Microsoft Graph API?
The Microsoft Graph API uses OAuth which makes permissions more visible in the form of scopes.
The Graph server will request the following delegated permissions:
-
Send email on behalf of users
-
Read and write user’s own and shared mailboxes
-
Sign in and read user profile
-
Sign users in
-
View user's basic profile
You can also check the permission scopes directly from within the add-in manifest XML:
Read more about how delegated permissions work at this page from Microsoft.
Full Graph permissions reference is available here.
What are delegated permissions?
With delegated permissions, an app is acting on the user's behalf. When user clicks the Hoxhunt Outlook add-in (which uses delegated permissions), the app is given a token that enables it to act under the user's authority within set and specific limits. The limits are defined by the scopes mentioned earlier. The token is only valid for a short period of time. Hoxhunt add-in will execute relevant actions based on your organisation’s Hoxhunt settings and the actions user takes in the UI. Hoxhunt never stores the token anywhere. The token will be lost forever once a reporting process has been completed.
Why are you using delegated permissions instead of app permissions?
Security-wise, delegated permissions are more convenient than app permissions. Delegated permissions require a logged-in user to act on behalf of, whereas app permissions can do "whatever , whenever", but cannot act on the user's behalf.
Why are we requiring the permissions we're requiring?
Send email on behalf of users
When reporting a possible malicious email – Hoxhunt add-in will use the requested permissions when reporting/forwarding a suspicious email from the users' mailbox to organizations redirect address (for Threat Forwarding)
Read and write user’s own and shared mailboxes
Used for reading the email being reported – be it a simulation email or a potential threat – as our add-in identifies the email being reported by the header information, we need this specific permission to be able to identify simulations, potential known threats, and safe emails (for Feedback Rules and instant feedback)
Sign in and read user profile
As we’re using delegated permissions instead of App permissions – we can always use the lowest necessary privileges – An application using delegated permissions requires a signed-in user to be present for making GraphAPI calls.
With Outlook REST API, Hoxhunt Outlook add-in was using an older permissions model. The add-in was granted effectively the same permissions as will be granted for Microsoft Graph API. (Except we're able to utilize less privileges now using delegated permissions)
Isn't there a separate AAD App we should register for Graph API?
No, customers don't need to register a separate ADD App. Hoxhunt has already registered the add-in to Microsoft Identity platform, and has set up the necessary AAD App to allow only delegated permissions for the add-in.
Does anything change security-wise when moving to Microsoft Graph API?
No significant changes will take place. With Outlook REST API, Hoxhunt Outlook add-in was using an older permissions model. The add-in was granted effectively the same permissions as will be granted for Microsoft Graph API.
How do we know if we should apply this change?
To prevent any potential issues in the future, we highly urge all our customers to update their Hoxhunt add-in to the latest version (v1.0.0.7 at the time of writing) in any case. This ensures you have the latest add-in version supporting our latest features and improvements, including support for Graph API.
How can we check if we have already applied this change or if we are already using the latest 1.0.0.7 version?
There are multiple ways to check your Hoxhunt add-in's current version.
One simple option is to attempt to update the add-in. The update will fail if you already have the latest version deployed.
If you have deployed Hoxhunt add-in through on-premise Exchange Admin Center, you can check the add-in's details for the version number.
If you have deployed Hoxhunt add-in through Centralized Deployment in M365, you can check the add-in's details for the version number here.
With M365, you can also check if you can see the five new Graph API permissions under Azure > Enterprise Applications > Hoxhunt Report > Security > Permissions.
(If you cannot locate Hoxhunt Report from the applications list, make sure you remove all pre-defined search filters in All applications view first.)
We are running on-premise Exchange Server and it only supports EWS API. Should we update the add-in anyways?
We highly recommend to update your Hoxhunt add-in to the latest version (v1.0.0.7 at the time of writing) even if you don't have any mailboxes in Exchange Online supporting the deprecated Outlook REST 2.0 API. This ensures you have the latest add-in version supporting our latest features and improvements, including support for Graph API.
How do on-premise/hybrid Exchange customers update the add-in?
Update add-in option is only available when add-in has been deployed via Centralized Deployment. If you have deployed Hoxhunt add-in via Exchange Admin Center > organizations > add-ins, you cannot use Centralized Deployment to update the add-in. In such case you first need to remove the deployed Hoxhunt add-in and then re-deploy it. See this page for more information.
How does the switchover impact end users?
If you have used Centralized Deployment for the updating, the add-in will only require approval of the new MS Graph API from the Admin, and for end users the transition will be transparent.
However, if you have not used Centralized Deployment you will need to remove the add-in and then reinstall it which will cause a short service disruption. It can take anywhere between 1 minute to 24 hours to remove the add-in and another similar time to re-deploy it - there are no exact guarantees on the completion time from Microsoft.
While the switch-over to the new add-in version is often quick, it is advisable to perform the update outside working hours. If end users have trouble seeing the add-in or they get an error while using it, first ask the users to restart their Outlook (this will refresh the add-in cache). If users continue having issues, please contact Hoxhunt Support along with the unique Trace ID and Error message.
I have more questions
Please contact support@hoxhunt.com for more information about the Microsoft Graph API or for more information about how your organisation can move over to the new API.