Connecting your Microsoft Report Button with Nimblr will allow the Administrators & Group Auditors to track and display in your portal which users are in fact reporting the Nimblr Phishing Simulations or not.
How does the Microsoft Report Button integration with Nimblr work?
When a user clicks the Microsoft “Report” button:
-
Microsoft sends a copy of the reported email to a shared mailbox that you configure.
-
Nimblr does not access user mailboxes.
-
Nimblr only reads emails that exist inside the dedicated shared mailbox.
-
Nimblr analyzes whether the reported message matches an active phishing simulation.
-
The user receives an email notification with positive feedback after successfully reporting a Nimblr simulation.
-
The result is displayed in the Nimblr portal for reporting and tracking purposes.
You can find the FAQ for the MS Report Button Integration here
Create a new shared mailbox.
-
Go to: https://admin.cloud.microsoft/?#/SharedMailbox and create a new shared mailbox.
-
Go to: https://security.microsoft.com/securitysettings/userSubmission. Make sure Monitor reported messages in Outlook and Use the built-in Report button in Outlook are selected, then set Send reported items to to either Microsoft and my reporting mailbox or My reporting mailbox only.
-
In Add an Exchange Online mailbox to Send reported items to, select the shared mailbox you just created.
In the Customize messages you can choose to customize the message the user receives after reporting the email.
Click on Customize messages then Add Customized message and choose the option Phishing Reported and then fill in Title & Description.
Make sure reported messages reach the mailbox unfiltered.
Microsoft requires the reporting mailbox to be registered as a SecOps mailbox in the Advanced Delivery policy. Without this registration, Microsoft's filtering stack may quarantine or modify reported messages before Nimblr can read them.
-
Go to: https://security.microsoft.com/advanceddelivery and open the SecOps mailbox tab.
-
Select Add (or Edit if there are already entries), select the shared mailbox you created, then select Add and Close.
If your organization uses data loss prevention (DLP), exclude the shared mailbox from your DLP policies as well.
Create and configure a New App Registration.
Why is this needed?
The integration uses:
-
Microsoft Graph
-
Application permission: Mail.Read
Application permissions are required because:
-
The shared mailbox is not tied to a single signed-in user session.
-
The integration runs as a background service.
Delegated permissions require a logged-in user context and are therefore not suitable for automated processing of a shared mailbox.
New App Registration.
-
Go to: https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
-
Then create a new app registration
-
Go to API permissions, click: Add a permission, and select Microsoft Graph.
-
Choose: Application permissions,select Mail.Read and click Add permissions then
Click Grant admin consent for… and select Yes when prompted
-
Go to Certificates and secrets and create a new secret.
If your organization enforces strict security policies in Microsoft 365, creating a new client secret may be restricted. You may need an Admin to grant you the right role (e.g. Application Administrator) or temporarily adjust your tenant's application management policy before the secret can be created.
-
Copy the Value (not the Secret ID) and store it securely (e.g., in a password manager). Important: The secret value is only shown once — it cannot be retrieved after you leave this page.
-
Go to Overview and copy: Application (client) ID and Directory (tenant) ID in the same document as the Client secret
Limiting the permissions.
Nimblr strongly advocates for the principle of least privilege. Assigning accounts only the minimum permissions necessary to perform their tasks helps reduce security risks and strengthens your organization's overall protection.
By default, Mail.Read (Application) technically grants the ability to read all mailboxes in the tenant.
However:
-
Nimblr only queries the specific shared mailbox configured
-
No logic exists to enumerate or access other mailboxes
To limit the app registration to only the shared mailbox, use Role Based Access Control for Applications in Exchange Online (Application RBAC). It replaces Application Access Policies (New-ApplicationAccessPolicy), which Microsoft now lists as legacy and advises against using for new setups. You grant Mail.Read through Exchange Online instead of Microsoft Entra ID, limited to a scope you define, and then remove the tenant-wide permission you granted in the previous section.
What this does:
-
The app can only access mailboxes inside that security group
-
If it tries to access any other mailbox, access is denied by Exchange Online
-
Enforcement is handled by Microsoft's backend
You need to be a member of the Organization Management role group in Exchange Online and have the Exchange Administrator role in Microsoft Entra ID to run these steps.
Set up group & scope.
-
Open up PowerShell and run the following command to sign in:
Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com
2. Create a new distribution group:
New-DistributionGroup -Name "API-Access-Group-V2Security" -Type Security -members yoursharedmailbox@domain
3. Create a management scope that points to that group:
$dn = (Get-Group "API-Access-Group-V2Security").DistinguishedName
New-ManagementScope -Name "Nimblr Report Button Scope" -RecipientRestrictionFilter "MemberOfGroup -eq '$dn'"
Only direct members of the group are in scope. Nested groups are not supported.
4. Find the app's IDs. In the Microsoft Entra admin center, go to Enterprise applications, open the Nimblr app and copy the Application ID and the Object ID. Use the values from Enterprise applications, not from App registrations. The Object ID is different on the two pages.
5. Register the app in Exchange Online:
New-ServicePrincipal -AppId <Application ID> -ObjectId <Object ID from Enterprise applications> -DisplayName "Nimblr Report Button"
6. Give the app Mail.Read, limited to the scope:
New-ManagementRoleAssignment -App <Object ID> -Role "Application Mail.Read" -CustomResourceScope "Nimblr Report Button Scope"
7. Test the result:
Test-ServicePrincipalAuthorization -Identity <Object ID> -Resource yoursharedmailbox@domain
InScope should be True for the shared mailbox.
Run it again with any other mailbox and it should be False.
The test only shows permissions granted through Exchange Online, so it does not show the tenant-wide permission from Microsoft Entra ID.
8. Once the test passes, remove the tenant-wide permission. In the Microsoft Entra admin center, open the Nimblr app registration, go to API permissions and remove Mail.Read (Application). If you leave it in place, it stays unscoped and the scope you just created has no effect.
Changes to app permissions can take from 30 minutes up to 2 hours to take effect.
Already using an Application Access Policy?
Existing policies keep working for now, but Microsoft recommends moving to Application RBAC. You can switch without interrupting the integration. Complete steps 3 to 8 above first (you can reuse the group the policy already uses), then remove the old policy:
Get-ApplicationAccessPolicy Remove-ApplicationAccessPolicy -Identity "<policy identity>"The scope filter only works with groups that Exchange Online recognizes (distribution groups, mail-enabled security groups and Microsoft 365 groups). A security group that exists only in Microsoft Entra ID does not work.
See Microsoft's migration guidance for details.
Configure in the Nimblr Portal.
-
Go to Settings tab > Report Button
-
Fill in the following credentials: Application (client) ID, Directory (tenant) ID and Client secret
-
Select the mailbox you created in step 1.
-
Optional but recommended: You can add our course to the library by going to Groups > Edit > Technology > Click the checkbox Report Phishing Emails.
This course explains how to make the best use of Microsoft's built-in Report Button. -
Now it's Done!