MailboxOS · Help · Tenant Connector

The tenant connector

How organization-wide mailbox access works, the exact Microsoft Entra permissions MailboxOS needs, and how to fix the errors you may see when setting it up or browsing mailboxes.

What it is

The tenant connector is an app registration you create and control in your own Microsoft Entra (Azure AD) tenancy. You grant it read-only permission, then enter three values — Directory (tenant) ID, Application (client) ID, and a client secret — under Settings → Tenant Connector. No MailboxOS software runs inside your tenancy, and you can revoke access at any time by deleting the app registration (or its secret) in Entra, or removing the connector in Settings.

Permissions it needs, and why

Both are Application permissions on Microsoft Graph (not delegated), and both need admin consent:

PermissionTypeWhy MailboxOS needs it
Mail.Read Application Reads and analyzes the mailboxes you submit. This is the core mail-export permission. Read-only — MailboxOS can never send, modify, or delete mail.
User.Read.All Application Powers the Browse mailbox pick-list (in New Analysis and Settings). It reads your directory so users can choose a mailbox from a searchable list instead of typing addresses. Directory access is separate from mail access — without it, mail export still works but Browse cannot list mailboxes.

Mail works but Browse doesn't? That is the classic symptom of a connector that has Mail.Read but is missing User.Read.All (or its admin consent). Add it using the steps below.

Add a permission & grant admin consent

  1. Sign in to the Microsoft Entra admin center as a Global Administrator (or Privileged Role Administrator).
  2. Go to Identity → Applications → App registrations and open your MailboxOS Connector app.
  3. Open API permissions → Add a permission.
  4. Choose Microsoft Graph → Application permissions.
  5. Search for and tick Mail.Read and User.Read.All, then Add permissions.
  6. Back on the API permissions page, click Grant admin consent for <your org> and confirm. The Status column must show a green “Granted for <your org>” for each permission — without consent, exports and Browse both fail.

Client secret expiry & rotation

The client secret you entered has an expiry date (set when you created it under Certificates & secrets). When it expires, exports and Browse stop working until you rotate it: create a new client secret in Entra, copy its Value (not the Secret ID), then re-enter it under Settings → Tenant Connector → Replace credentials. Put a calendar reminder a couple of weeks before the expiry date.

Troubleshooting the errors you may see

Message in MailboxOSWhat it means & how to fix it
The tenant connector isn't set up yet. No connector has been saved for your organization. Add your Entra app credentials under Settings → Tenant Connector. (You need the owner or admin role.)
Microsoft rejected the connector's sign-in. The stored credentials no longer work: the client secret has expired or was changed (AADSTS7000222 / AADSTS7000215), or the app / tenant details are wrong or the app was removed (AADSTS700016). Rotate the secret (see above) or re-check the Directory and Application IDs, then re-save under Settings → Tenant Connector.
The connector can sign in and read mail, but it isn't allowed to list mailboxes. The app is missing the User.Read.All application permission or its admin consent (Graph returns Authorization_RequestDenied). Add User.Read.All and grant admin consent using the steps above, then try Browse again. Mail export is unaffected in the meantime.
Couldn't reach Microsoft just now. A temporary network, throttling, or Microsoft service issue. Wait a moment and try again. If it persists, check the Microsoft 365 service status.

For the full IT-admin walkthrough — creating the app registration, creating a secret, and scoping mail access to specific mailboxes — see the Tenant Connector Setup Guide (docs/CONNECTOR_SETUP.md), linked from the Settings → Tenant Connector card.

MailboxOS · Tenant Connector help