# Azure app registration — Outlook / Microsoft Graph Mail

One-time setup for mailx itself (not per-user). Public-client OAuth means the **app** (mailx) registers once; end-users just sign in with their own Microsoft accounts at runtime and consent at first use. The client ID is public, baked into the source tree.

This is the same model mailx already uses for Google: one Google OAuth client committed with the code, every user signs in with their own Google account.

## 1. Register the app (one time, by the mailx author)

1. Go to https://portal.azure.com → search **App registrations** → **New registration**.
2. Fill in:
    - **Name:** `mailx` (just a label; users won't usually see it)
    - **Supported account types:** *Accounts in any organizational directory … **and** personal Microsoft accounts*. This lets both consumer (`@outlook.com`) and work/school (`@company.com`) users sign in to their own accounts.
    - **Redirect URI:** pick **Public client/native** and enter `http://localhost`. oauthsupport uses the OAuth2 loopback flow; no fixed port is needed because the redirect URI is treated as a prefix.
3. **Register**. From the Overview page, copy the **Application (client) ID** — a GUID like `12345678-abcd-…`. Public clients have no client secret.

## 2. Grant Graph scopes

4. Left nav → **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated permissions**. Check:
    - `Mail.ReadWrite` — read + modify messages (flags, move, delete)
    - `Mail.Send` — send mail
    - `offline_access` — **required** for refresh tokens; without it the session dies after an hour
    - `User.Read` — fetch display name + email for account labeling
5. Click **Add permissions**. Admin consent isn't needed for personal accounts — each end-user grants it at first sign-in on their own machine.

## 3. Allow public-client flows

6. Left nav → **Authentication** → scroll to *Advanced settings* → **Allow public client flows** = **Yes** → **Save**. This lets the loopback redirect work without a client secret.

## 4. Ship the client ID with mailx

7. Commit the client ID into the mailx source tree the same way the Google client ID is committed. Candidate locations (pick whichever matches existing convention for Google):
    - `oauthsupport` has a provider-keyed constants file — add a `microsoft` entry next to the existing `google` one, with:
        - `client_id`: the GUID from step 1
        - `tenant`: `"common"` (accepts both personal and work/school accounts)
        - `auth_uri`: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`
        - `token_uri`: `https://login.microsoftonline.com/common/oauth2/v2.0/token`
        - `redirect_uri`: `http://localhost`
    - or a mailx-level `providers/microsoft.json` if oauthsupport expects per-provider JSON.
8. Per-user tokens (refresh + access) still live in `~/.mailx/tokens/<user-email>/` the same as today — that's where the *user-specific* state goes. The client ID is not in `~/.mailx/`; it ships with the app.

`tenant` options if needed:
- `"common"` — both personal and work/school (default for mailx)
- `"consumers"` — personal only
- a specific tenant GUID — single-tenant, work-only

## 5. Test

The Outlook dispatcher wiring (`isOutlookAccount()` / `getOutlookProvider()`) inside `ImapManager` is still a TODO — see *Outlook Graph API driver — full wiring* in TODO.md. Registration above gets the credentials baked into the code so the dispatcher work can flip the switch without further Azure work.

## Production app verification

Not needed until mailx is distributed outside Bob's family / close circle. Unverified apps show a "this app wasn't verified by Microsoft" warning on the consent screen — users can proceed through it. Verification requires a publisher domain + privacy policy + terms of service; skip until it matters.

## Reference links

- OAuth2 authorization code flow with PKCE: https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow
- Graph Mail API reference: https://learn.microsoft.com/graph/api/resources/mail-api-overview
- Throttling guidance (mirrors Gmail's model — token bucket + Retry-After): https://learn.microsoft.com/graph/throttling
