# 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 Mail.Read application permission

1. On the new app's page, open **API permissions → Add a permission**.
2. Choose **Microsoft Graph → Application permissions**.
3. Search for and tick **Mail.Read** (under *Mail*), then **Add permissions**.
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\>" — without this, exports will fail.

You can remove the default delegated `User.Read` permission if you like; it
is unused.

## 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.

**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).