Help PhishTrainer: setup
Microsoft 365 Outlook add-in: administrator guide
The PhishTrainer button icon in your mailbox
On this page
Overview
The PhishTrainer Outlook add-in adds a Report button to Outlook, in a “PhishTrainer” group. Your employees use it to send a suspicious email (phishing or spam) to your organization's security team, via PhishTrainer.
The add-in is published by Tesweb SA (Ins, Switzerland), a publisher verified by Microsoft. PhishTrainer is Bexxo software. Bexxo is the cybersecurity division of Tesweb SA. The add-in is hosted by PhishTrainer: updates are automatic, nothing to reinstall.
Supported Outlook clients
- Outlook on the web;
- the new Outlook for Windows;
- Microsoft 365 Outlook (desktop app);
- Outlook mobile (iOS and Android).
The button is shown on a received email, opened for reading. It does not appear while a message is being written.
Prerequisites: Exchange Online mailboxes. Outlook versions without a subscription (2016, 2019, 2021) use the Outlook VSTO add-in, another PhishTrainer product.
Data and permissions
What PhishTrainer receives when an email is reported
- the complete reported email (EML format, including attachments);
- the type chosen by the employee (Phishing or Spam) and the boxes they ticked (link clicked, attachment opened, password or information entered, reply or call);
- the Outlook language;
- your Microsoft 365 tenant ID, the employee's ID and their address (UPN), read from the Microsoft Entra token.
The employee has no PhishTrainer account or password: they are identified by their Microsoft 365 account. The add-in does not log any token, activation code or message content.
Maximum size of a report: 3 MB, including attachments. Above that, the add-in offers to send the email without its attachments (each attachment is replaced by a line giving its name and size), or to forward it to the IT department.
Data is hosted exclusively in Switzerland. The retention period for reported emails is set by the contract between your organization and Bexxo.
Microsoft Entra applications and permissions
Two multitenant Entra applications, published by Tesweb SA, are used.
“PhishTrainer Report” (the add-in), application ID 40000108-0758-46fa-b771-bea24c72d6b1. Microsoft Graph delegated permissions:
| Permission | Use |
|---|---|
openid, profile, offline_access, User.Read | User sign-in. |
Mail.Read | Read the reported email when Outlook cannot provide it itself (mobile, older versions of Outlook). |
Mail.ReadWrite | Move the reported email to Deleted Items, only if the option is enabled. |
access_as_user (PhishTrainer API) | Send the report to PhishTrainer on behalf of the user. |
“PhishTrainer Liaison M365”, application ID 3b5001b0-f842-4be5-ab80-4c58962ed369: used only once by the administrator to link the tenant. Permissions openid, profile and email only (identity, no access to emails).
These IDs are not secrets. They are used to find the applications in Enterprise applications in Microsoft Entra, or to target them in a Conditional Access policy.
1Create the source in PhishTrainer
- In PhishTrainer, open Receiving reports, then click Add a source.
- Choose Microsoft 365 Outlook add-in.
- In the Settings tab, decide whether the Delete the email after reporting option should be enabled: once the report has been accepted by the server, the add-in moves the reported email to the employee's Deleted Items, from where it can still be recovered.
- Save. A fallback activation code is then shown; it is only used if the tenant is not linked (see step 2).
2Link your Microsoft tenant
The link allows PhishTrainer to recognize your employees automatically: with a linked tenant, no code is requested.
- In the Installation tab of the source, click Link my Microsoft tenant.
- Sign in with a Microsoft 365 administrator account: global administrator or application administrator.
- Accept the consent request of the “PhishTrainer Liaison M365” application.
The link appears in the Links and users tab. Without a link, PhishTrainer remains usable with the fallback activation code.
3Deploy the add-in for the organization
Centralised deployment installs the add-in with no action from employees.
- In the Microsoft 365 admin center, open Settings › Integrated apps › Upload custom apps.
- Choose Office Add-in and enter the manifest URL (recommended: its updates are picked up automatically), or upload the file.
- Assign the add-in to the whole organisation, or to users and groups (top-level groups only: nested groups are not supported). Choose the Fixed mode: installed by default, cannot be removed.
- Accept the permissions requested by PhishTrainer (reading and moving emails) for the whole organisation: without them, there is no automatic deletion after reporting.
Timing: the add-in usually appears within a few hours, up to 24 hours. Restarting Outlook may be needed.
Alternative: installation by each employee
Without centralised deployment, each employee can install the add-in themselves:
- In Outlook, open Apps › Add apps (depending on the version: Get add-ins).
- Choose My add-ins › Add a custom add-in › Add from URL, then paste the manifest URL.
- Open an email and click the PhishTrainer button.
- If the tenant is not linked, the pane offers to activate the add-in: paste the fallback activation code. The Microsoft account is then recognised on all of the user's devices, with nothing more to enter.
The Message to employees tab of the source provides ready-to-send text, with the manifest URL and the activation code, in the interface language.
Your organisation may block custom add-ins: in that case, use the organisation-wide deployment.
Check that everything works
With the account of an employee covered by the deployment: open a received email, click Report. The PhishTrainer pane opens and shows “What do you want to report?” with the choice Phishing / Spam.
On first use, a Microsoft sign-in or permission window may open.
Troubleshooting
| What you see | Likely cause | What to do |
|---|---|---|
| Button missing | Deployment not yet propagated, user outside the assigned groups, or message being written | Wait up to 24 h, restart Outlook, check the assignment, open a received message |
| “Your organization is not yet linked to PhishTrainer…” | Tenant not linked | Link the tenant (step 2), or enter the fallback activation code |
| “Your company must allow PhishTrainer…” | Administrator consent missing | Accept the permissions for the organization (step 3) |
| “The reporting service is disabled…” | Source disabled in PhishTrainer | Re-enable the source |
| “Your access has been removed…” | Employee's access removed by the administrator | If the removal was not intended: Restore in the Links and users tab |
| “Unable to connect to Microsoft” | Token rejected or sign-in cancelled | Try again |
| “Too many requests in a short time” | Limit reached (60 reports per user in 10 minutes) | Try again in a few minutes |
| “Email too large” | More than 3 MB, including attachments | Send without attachments, or forward to the IT department |
| Link: “Only an administrator of your Microsoft 365 organisation can link it.” | Account without the global administrator or application administrator role | Redo the link with the right account |
| Link: “This Microsoft 365 tenant is already linked to another organization.” | Tenant attached to another PhishTrainer account | Contact support |
| Link: “Create and save the source first, then link your organization.” | Source not yet saved | Complete step 1 |
Support: for any question about the installation, write to info@bexxo.ch.
Manage access, suspend or uninstall
In PhishTrainer
| Action | Effect |
|---|---|
| Revoking a user | Only that person loses access, even if the tenant is linked. “Restore” gives access back. |
| Revoking the tenant link | Automatic recognition stops. Employees recognised through the link must activate PhishTrainer with the code; those activated by code are not affected. |
| Turning off reception (switch in the Settings tab) | All users see that the service is disabled. When it is turned back on, everything works again with nothing to enter: the Microsoft account is what counts. |
| Regenerating the code | Users already activated keep working. Only new activations by code need the new code; update the message to employees. |
In Microsoft 365
- Remove the button: delete the add-in in Settings › Integrated apps in the Microsoft 365 admin center.
- Revoke the permissions: in Microsoft Entra, Enterprise applications, find “PhishTrainer Report” and “PhishTrainer Liaison M365” using their IDs.
Microsoft portal labels change regularly: if a menu does not match exactly, search for the add-in or the application by its name.
Didn’t find the answer? Contact us