# MailboxOS Tenant Connector — IT Admin Setup Guide

This guide is for the Microsoft 365 / Entra administrator of a customer
organization. It walks through creating the app registration that lets
MailboxOS export and analyze mailboxes in your tenancy. Allow ~10 minutes.

**What you are setting up.** MailboxOS reads mailboxes through an app
registration that *you* create and control in your own Entra tenancy. You
grant it read-only mail permission, then enter three values (tenant ID,
client ID, client secret) in MailboxOS Settings. No MailboxOS software runs
inside your tenancy, and you can revoke access at any time by deleting the
app registration or its secret.

**You need** a role that can grant tenant-wide admin consent — Global
Administrator or Privileged Role Administrator.

## Step 1 — Create the app registration

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com)
   and go to **Identity → Applications → App registrations → New registration**.
2. **Name**: `MailboxOS Connector` (any name works; this is what appears in
   your audit logs).
3. **Supported account types**: *Accounts in this organizational directory
   only* (single tenant).
4. **Redirect URI**: leave empty — this app is never used interactively.
5. Click **Register**.

## Step 2 — Grant the Graph application permissions

1. On the new app's page, open **API permissions → Add a permission**.
2. Choose **Microsoft Graph → Application permissions**.
3. Search for and tick these, then **Add permissions**:
   - **Mail.Read** (under *Mail*) — **required**. Lets MailboxOS read and
     analyze the mailboxes you submit.
   - **User.Read.All** (under *User*) — **required for mailbox discovery**,
     optional otherwise. It powers the **pick-a-mailbox list** in MailboxOS
     (Settings / new-run) so your users choose a mailbox from a searchable
     directory list instead of typing addresses by hand. If you skip it,
     everything still works but users must type each mailbox address exactly;
     the pick-list will be empty.
4. 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 this, exports
   (and discovery) will fail.

You can remove the default delegated `User.Read` permission if you like; it
is unused (the discovery pick-list uses the **application** `User.Read.All`
above, not the delegated one).

> **Discovery vs. export, and mailbox scoping.** Mailbox discovery reads your
> **directory** (`User.Read.All`), which is separate from mail access
> (`Mail.Read`). If you scope mail access to a security group with an
> application access policy (see *Security* below), the pick-list will still
> show **every** mailbox in your tenancy — including ones outside the policy
> group that MailboxOS cannot actually export. This is expected: an export of
> an out-of-scope mailbox simply fails with an access-denied error. If you
> want the pick-list itself to be narrower, either omit `User.Read.All`
> (users type addresses) or scope the directory read too (not covered here).

## Step 3 — Create a client secret

1. Open **Certificates & secrets → Client secrets → New client secret**.
2. Description: `MailboxOS`; expiry: 12–24 months is a sensible balance.
3. **Copy the secret's *Value* immediately** — it is shown only once (the
   *Secret ID* column is NOT the secret; you need *Value*).

**Expiry management**: when this secret expires, MailboxOS exports stop
working until you create a new secret here and re-enter it in MailboxOS
Settings. Put a reminder in your calendar a couple of weeks before the
expiry date you chose.

## Step 4 — Collect the three values

From the app's **Overview** page:

| Value | Where |
|---|---|
| Directory (tenant) ID | Overview page |
| Application (client) ID | Overview page |
| Client secret value | copied in Step 3 |

## Step 5 — Enter them in MailboxOS

In MailboxOS, go to **Settings → Tenant Connector**, paste the three values,
and save. MailboxOS validates them immediately by requesting a token from
Microsoft — if anything is wrong, the exact Microsoft error is shown (see
Troubleshooting below). On success the connector status shows **Configured**
and anyone in your MailboxOS organization can start analyses against
mailboxes in your tenancy.

## Security: what this grants, and how to narrow it

Application-permission `Mail.Read` is **read-only** — MailboxOS can never
send, modify, or delete mail. However, by default it applies to **all
mailboxes in your tenancy**. MailboxOS only reads the mailboxes you
explicitly submit for analysis, but the *permission* itself is tenant-wide
unless you scope it.

**Recommended: restrict the app to specific mailboxes** with an
[application access policy](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access).
Create a mail-enabled security group containing only the mailboxes MailboxOS
may read, then in Exchange Online PowerShell:

```powershell
Connect-ExchangeOnline

New-ApplicationAccessPolicy `
  -AppId "<Application (client) ID from Step 4>" `
  -PolicyScopeGroupId "mailboxos-allowed@yourdomain.com" `
  -AccessRight RestrictAccess `
  -Description "Restrict MailboxOS to approved mailboxes only"

# Verify: should return AccessCheckResult Granted / Denied as expected
Test-ApplicationAccessPolicy `
  -AppId "<Application (client) ID>" `
  -Identity "someone@yourdomain.com"
```

The policy can take up to ~30 minutes to take effect. Once active, an export
request for a mailbox outside the group fails with an access-denied error —
add the mailbox to the group to allow it.

Note the policy applies to **mail access only**. MailboxOS's mailbox
**discovery** pick-list (powered by `User.Read.All`, Step 2) reads the
directory and is *not* restricted by an application access policy, so it will
still list mailboxes outside the group; only the eventual **export** honors
the policy (out-of-scope picks fail on export as above).

**Revoking access entirely**: delete the client secret (or the whole app
registration) in Entra, and/or remove the connector in MailboxOS Settings —
removing it in MailboxOS deletes the stored credentials.

## Troubleshooting

MailboxOS validates the connector by acquiring a token from Microsoft the
moment you save it, so most mistakes surface immediately in Settings with
the Microsoft (AADSTS) error text:

- **`AADSTS700016` — "Application ... was not found in the directory"**:
  the Application (client) ID is wrong, or the Directory (tenant) ID belongs
  to a different tenancy than the app registration. Both must come from the
  same app's Overview page.
- **`AADSTS90002` — "Tenant ... not found"**: the Directory (tenant) ID is
  mistyped. Copy it again from the Overview page.
- **`AADSTS7000215` — "Invalid client secret provided"**: the secret value
  is wrong — the most common cause is pasting the *Secret ID* instead of the
  *Value*. Create a new secret and paste its Value.
- **`AADSTS7000222` — "...client secret keys ... are expired"**: the secret
  has expired. Create a new one (Step 3) and re-save in MailboxOS.
- **Connector saves fine but exports fail with an authorization/access
  denied error**: admin consent was not granted (Step 2 — the Status column
  must show green "Granted"), or an application access policy is excluding
  that mailbox (add it to the policy's group and wait ~30 minutes).
- **Connector saves fine and mail export works, but the "Browse" mailbox
  pick-list fails** ("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. Mailbox discovery reads the
  directory (`User.Read.All`), which is separate from mail access
  (`Mail.Read`) — so a connector can export mail yet be unable to enumerate
  mailboxes. Graph returns `403 Authorization_RequestDenied`. Add
  `User.Read.All` (Step 2) and grant admin consent, then retry Browse. Users
  can keep typing mailbox addresses by hand in the meantime.

In-app, each of these surfaces as a specific message with a **"What to fix"**
link to the built-in help page (`/help/connector.html`), which repeats these
fixes for end users who aren't the IT admin.
