Skip to content

Microsoft 365 connection

The app sends the report email through Microsoft 365. This page sets that up. It assumes no prior Azure/Entra experience.

You need to be a Microsoft 365 Global Administrator (or have an admin do the consent step). If you're not, ask your IT admin to do this page with you.

This is a different registration from the login one

If you also set up Cloudflare Access login (see Access & configuration), that uses its own, separate Entra app registration. Do not reuse it here. Create a brand-new registration on this page, dedicated to sending mail.

1. Create the app registration

  1. Go to https://entra.microsoft.com and sign in as an administrator.
  2. In the left menu, select Identity → Applications → App registrations.
  3. Click + New registration at the top.
  4. Name: type something clear like Cove Audit Reporter – Mail.
  5. Supported account types: choose Accounts in this organizational directory only (Single tenant).
  6. Leave Redirect URI empty for now.
  7. Click Register.

You now land on the app's Overview page.

2. Copy the two IDs

On the Overview page, under Essentials, copy and save these:

  • Application (client) ID
  • Directory (tenant) ID

You'll paste them into the config file in step 6.

3. Add the redirect URI (as a Mobile and desktop application)

  1. In the left menu of your app, under Manage, select Authentication.
  2. Click + Add a platform.
  3. In the panel that opens, select the Mobile and desktop applications tile.

  4. Ignore the suggested checkboxes; in the Custom redirect URIs box enter exactly:

    https://<your-domain>/api/v1/admin/m365/callback

    Replace <your-domain> with your real domain, e.g. https://cove.totlcom.com/api/v1/admin/m365/callback. 5. Click Configure.

Use Mobile and desktop, not Single-page application

This app redeems the sign-in code server-side (in the Worker). The Single-page application platform blocks that (AADSTS9002327: ... may only be redeemed via cross-origin requests). The Mobile and desktop applications platform is a public client — still PKCE, still no client secret — and allows server-side redemption. The path must end in /api/v1/admin/m365/callback.

4. Add the Graph permissions

  1. In the left menu, select API permissions.
  2. Click + Add a permission → Microsoft Graph → Delegated permissions.
  3. Search for and tick each of these, then click Add permissions:
    • Mail.Send
    • Mail.Send.Shared
    • offline_access
    • User.Read
  4. Back on the API permissions list, click ✓ Grant admin consent for \<your organization>, then Yes. Each permission's Status column should turn green ("Granted").

5. Set up the shared mailbox

Reports are sent from one shared mailbox (for example reports@totlcom.com), and the person who clicks Connect must have permission to send as it.

  1. Go to the Exchange admin center at https://admin.exchange.microsoft.com.
  2. In the left menu, select Recipients → Mailboxes (for a shared mailbox use Recipients → Shared, or create one with + Add a shared mailbox).
  3. Open the mailbox you'll send from → Delegation (or Manage mailbox delegation).
  4. Under Send As, click Edit, + Add members, and add the user account that will click Connect Microsoft 365 in the app.
  5. Save. (Send-As permission can take a few minutes to take effect.)

6. Put the IDs in the config file

Open server/config/app.config.ts and fill in the values you copied:

m365: {
  senderUpn: "reports@totlcom.com",   // the shared mailbox
  tenantId: "PASTE_DIRECTORY_TENANT_ID",
  clientId: "PASTE_APPLICATION_CLIENT_ID",
  allowSendAsOtherMailboxes: false,
},

Save the file, then re-deploy so the change takes effect:

npm run deploy

7. Connect from the app

  1. Open the app and go to Admin.
  2. Click Connect Microsoft 365. You're sent to Microsoft to sign in — sign in as the account that has Send-As on the shared mailbox — and approve.
  3. You're returned to the app. Click Send test and confirm an email arrives from the shared mailbox.

That's it — the app is now connected.

Staying connected & reconnecting

  • The monthly job refreshes the connection automatically. Because it runs at least monthly, it stays connected indefinitely with no maintenance.
  • If a password reset, an admin action, or a security policy ever breaks it, the run fails, admins are emailed, and the dashboard shows Reconnect Microsoft 365. Click it and sign in again — one step, no portal.

Note

The connection secret (a refresh token) is stored encrypted and never shown in the app or logs. Reports can only ever be sent from the mailbox pinned in the config file.