Skip to content

Outlook "Report Phishing" Add-in

The BongoShield Outlook add-in puts the daily security question and a native Report Phishing button right inside the inbox, and — when you assign it to everyone — makes the daily gate a real part of opening email rather than an optional tool.

You deploy it yourself. The package and the per-organization secret it needs are both in Settings → Downloads, and the actual install is a standard Microsoft 365 centralized deployment you run from the Microsoft 365 admin center. You must be a BongoShield Owner or Admin to get the package, and a Microsoft Exchange or Global administrator to deploy it.

This is deployed centrally, not by employees

All BongoShield host-app plugins (Outlook add-in, browser extension, Roundcube plugin) are pushed org-wide by IT and made mandatory. Employees never see an "install BongoShield" prompt and can't remove a centrally-deployed add-in. A gate an employee could skip installing would defeat the point of the daily gate. See Gate Options for how these compare to sign-in delivery.

1. Get the package and note the add-in secret

  1. In BongoShield go to Settings → Downloads.
  2. Download the Outlook add-in package (bongoshield-outlook-addin-<version>.tar.gz) — hand this to whoever hosts it (see step 2). The download is admin-only and written to the audit log.
  3. On the same page, find the Add-in secret card. This is the per-organization shared secret the add-in host and the Roundcube plugin use to authenticate their server-to-server calls back to BongoShield (INTEGRATION_PLUGIN_SECRET). It is not a per-user credential and employees never see it. Click Regenerate add-in secret to reveal it — it is shown once, so copy it now. Regenerating invalidates the old value, so only rotate it when you're ready to redeploy the host with the new one.

2. Choose the manifest URL

Centralized deployment points Microsoft at a manifest URL. Which one depends on how BongoShield is deployed for you:

Deployment Manifest URL What it is
Cloud / pooled SaaS (app.bongoshield.com) https://addin.bongoshield.com/manifest.xml The shared, BongoShield-hosted add-in server. Identity is resolved per-tenant via Microsoft's Nested App Authentication after you've done Connect with Microsoft in SSO. No add-in secret needed for this path.
Dedicated / on-premise your own host, e.g. https://addin.<your-domain>/manifest.xml Host the downloaded tarball behind your own HTTPS, configured with your org's add-in secret from step 1, then point deployment at your own manifest URL.

Most cloud customers use the shared addin.bongoshield.com URL directly. Only download and self-host the tarball for a dedicated/on-prem install.

3. Deploy in the Microsoft 365 admin center

  1. Sign in to https://admin.microsoft.com as a Global Administrator or Exchange Administrator.
  2. Left navigation → Settings → Integrated apps.
  3. Select Upload custom apps. (On the legacy add-in portal some tenants still see: Add-ins → Deploy Add-in → Next → Upload custom app.)
  4. App type: Office Add-in.
  5. Choose "Provide link to manifest file" — not a local file. A URL lets Microsoft always fetch the current manifest, so future add-in updates roll out without you re-uploading anything. Paste the manifest URL from step 2.
  6. Validate → Next.
  7. Assignment: select Everyone (recommended — the whole point is that no employee is exempt). For a pilot, assign a specific group first, then widen to Everyone once confirmed.
  8. Deploy. A green checkmark confirms it was accepted.

Prerequisites

  • Admin role: Exchange Administrator (or Global Administrator). The Integrated apps page doesn't appear for other roles.
  • Every target user needs an Exchange Online (OAuth-enabled) mailbox on a standard Microsoft 365 Business/Enterprise plan. On-prem Exchange mailboxes aren't supported.
  • AppsForOfficeEnabled must not be False on the tenant (it's on by default; check with Get-OrganizationConfig | fl AppsForOfficeEnabled in Exchange Online PowerShell).

4. Verify the button appears

  • Allow up to 24–72 hours for the add-in to appear in every user's ribbon (Microsoft's own guidance — most tenants see it within a couple of hours). Relaunching Outlook picks it up sooner.
  • Open Outlook on the web (OWA) or the Outlook desktop client as a test user and confirm the Report Phishing button appears on the ribbon.

5. Test reporting

  1. Send yourself a harmless test message, open it, and click Report Phishing.
  2. Reporting a BongoShield phishing simulation credits the campaign and the employee; reporting a real suspicious message files it for your security team's triage queue. The employee sees the same acknowledgement either way, so the tests stay realistic.
  3. Confirm the daily security question is presented in the add-in when a user who hasn't answered yet opens their mail (subject to your gate settings).

Making it mandatory

Assigning the add-in to Everyone (or a dynamic "All employees" group) is the mandatory state — there's no separate toggle. A centrally-deployed line-of-business add-in is fixed: users can't remove or disable it from Outlook's "My add-ins". New hires in the assigned group inherit it automatically.

Other gate variants

The same Settings → Downloads page and add-in secret cover two more surfaces:

Browser extension (Chromium / Edge)

Download bongoshield-extension-<version>.zip and force-install it org-wide — it isn't published to a public store, so you push it by policy:

  • Google Workspace: Admin console → Devices → Chrome → Apps & extensions → Users & browsers → target the org unit → Force install (or Force install + pin).
  • Microsoft Intune (Edge): Devices → Windows → Configuration profiles → Settings catalog → ExtensionInstallForcelist → add <extension-id>;<update-url> → assign.
  • Group Policy (on-prem AD): set ExtensionInstallForcelist in the Chrome/Edge ADMX templates.

Force-installed extensions can't be removed or disabled by the user.

Roundcube webmail plugin

For organizations running their own Roundcube webmail (common for ministries and self-hosted email). Download bongoshield-roundcube-plugin-<version>.zip and install it once on the Roundcube server:

  1. Unzip into /var/www/roundcube/plugins/bongoshield/ and set ownership to the web user.
  2. Copy config.inc.php.dist to config.inc.php and set bongoshield_api, bongoshield_frontend, and bongoshield_shared_secret (your add-in secret).
  3. Add 'bongoshield' to the $config['plugins'] array in Roundcube's own config.inc.php.
  4. Reload PHP-FPM (e.g. sudo systemctl reload php8.2-fpm).
  5. Sign in as any user — the gate modal should block the mailbox until the daily question is answered.

It applies to every mailbox on that server immediately — there's no per-user step.

Plan availability

The Outlook add-in and Roundcube plugin require the mail plugins feature; the browser extension requires the browser extension feature. If a download is locked, it's not in your current plan — see Licensing & Seats.

Troubleshooting

Symptom Likely cause Fix
The Report Phishing button never appears Not enough time has passed, or the user hasn't relaunched Outlook Wait up to 24–72 hours; have the user restart Outlook.
Integrated apps page is missing in admin.microsoft.com Your admin role is too low Sign in as Exchange or Global administrator.
Manifest validation fails on upload Wrong URL, or the host isn't reachable over HTTPS Recheck the manifest URL (step 2); for self-hosting, confirm the add-in host serves manifest.xml over valid HTTPS.
Add-in loads but calls back fail (dedicated/on-prem) Wrong or rotated add-in secret on the host Copy the current Add-in secret (Settings → Downloads → Regenerate), set it as the host's INTEGRATION_PLUGIN_SECRET, and redeploy.
Daily question never gates in the add-in Plugin gating is turned off org-wide Turn Plugin gating back on in Settings → LDAP / AD (the org-wide plugin kill switch lives there).
A download shows "Upgrade to unlock" The feature isn't in your plan See Licensing & Seats.
A download shows "Not bundled in this image" The running image doesn't include that plugin artifact Re-install/upgrade from a release tag that bundles it.
Some users report but aren't matched Their Microsoft mailbox address differs from their BongoShield email Align the email in Settings → Users.