Hoxhunt's Outlook add-in needs certain permissions to work properly. The permissions are granted centrally by the M365 Administrator when Hoxhunt add-in is being installed to the tenant.
NOTE: This article is applicable to Hoxhunt OfficeJS add-in (manifest.xml).
In M365, Hoxhunt add-in works with Microsoft Graph for its operations.
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.
Why does Hoxhunt require the permissions?
Hoxhunt always pursues least-privileges approach when performing actions related to reporting an email with Hoxhunt button. For Microsoft Office Add-in framework, we need certain privileges for the core function to work. These rights are not active/available in the background for Hoxhunt, but only given for the add-in when user interacts with it by pressing the button. All permissions granted are temporary a short-lived (5 min).
Sign in (openid)
Sign users in and read user profile (user.read)
View user's basic profile (profile)
Basic rights needed for the add-in to operate above and identify user securely. Allows Hoxhunt add-in is identify the user and the organization they are associated with.
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.
Send email on behalf of users (mail.send.shared)
When reporting a possible malicious email, this allows Hoxhunt add-in to forward the reported suspicious to organization's redirect address (SOC mailbox etc.) directly from the email client without passing in through Hoxhunt.
Read and write user and shared mail (mail.readwrite.shared)
Used for identifying the email being reported by its headers – be it a simulation email or a potential threat. Hoxhunt needs this specific permission to be able to identify simulations, potential known threats, and safe emails from each other (for Feedback Rules and Instant Feedback).
This permission also allows users to report suspicious emails from shared mailboxes.
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.
Isn't there a separate Entra App we should register for Graph API?
No, customers don't need to set up a separate app registration. Hoxhunt has already registered the add-in to Microsoft identity platform, and has set up the necessary app registration to allow only delegated permissions for the Hoxhunt add-in. See below for further details.
How does Hoxhunt obtain permission to call Graph API in the first place? Do we need to provide you with Client secrets for the Hoxhunt app registration?
To meet the requirements of Microsoft Graph and Microsoft identity platform, Hoxhunt has set up a separate “multitenant” App registration to its own Microsoft Entra ID tenant in order to register Hoxhunt web application with the Microsoft identity platform. There is no need for customers to share their client secrets with Hoxhunt.
Read more here: https://learn.microsoft.com/en-us/graph/auth-register-app-v2
To call Microsoft Graph, Hoxhunt’s web application must obtain an access token from the Microsoft identity platform. This access token includes information about whether the app is authorized to access Microsoft Graph on behalf of a signed-in user (delegated access).
Read more here: https://learn.microsoft.com/en-us/graph/auth-v2-user?tabs=http
An exhaustive description of Microsoft Graph’s authentication and authorization concept is described here: https://learn.microsoft.com/en-us/graph/auth/auth-concepts
Permissions and consent in Microsoft identity platform: https://learn.microsoft.com/en-us/entra/identity-platform/permissions-consent-overview