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://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. The Microsoft 365 card shows a reminder that the account you connect must have Send As on the shared mailbox.
  2. Click Connect Microsoft 365. Microsoft now shows an account picker — choose the account you want the app to send as (see the recommendation below), then approve.
  3. You're returned to the app. The card shows Connected and Connected as: \<the account you chose>.
  4. Click Send test and confirm an email arrives from the shared mailbox.

That's it — the app is now connected.

Which account to connect — use a durable one, not a personal account

The connection is tied to the account you sign in with. If that account is later disabled, deleted, or has its password reset (for example, when a staff member leaves), the connection breaks and someone must reconnect.

Connect with an account that will outlast any one person — a Global Administrator or, better, a dedicated service account — that has Send-As on the shared mailbox. That way the reports keep flowing even after staff changes. The app shows Connected as on the Admin card so you can always see which account is in use.

Staying connected & reconnecting

  • The monthly job refreshes the connection automatically. Because it runs at least monthly, it stays connected indefinitely with no maintenance.
  • If the connected account's password is reset, the account is disabled/removed, or a security policy breaks it, the run fails, admins are emailed, and the dashboard shows Reconnect Microsoft 365. Click it, pick the account again, and approve — one step, no portal.
  • To change which account sends (e.g. move from a personal account to a service account), just click Reconnect Microsoft 365 and pick the other account. The Connected as line confirms the switch.

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.