> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suchi.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft mailbox sign-in

> Use Suchi's shipped device-code registration or a deployment override.

The Microsoft provider uses OAuth device code and XOAUTH2 for IMAP. The user
approves access in a browser; Suchi never sees the Microsoft password and never
uses a client secret.

Published builds ship a public-client registration for personal Microsoft
accounts and work or school accounts. Ordinary users only need to click
**Sign in with Microsoft**.

## Sign in

1. Administrators open **Settings > Archive configuration > Email intake**.
   Members with **Manage mailboxes** open **Settings > My account > Mailboxes**.
   Add a mailbox and choose **Microsoft**.
2. Enter the mailbox address. Administrators choose its Suchi owner; a member
   is selected automatically as the owner of their own mailbox.
3. Click **Sign in with Microsoft**.
4. Open the displayed Microsoft URL in any browser and enter the device code.
5. Approve the requested mailbox access.
6. Return to Suchi, save the mailbox, and run **Test connection**.

If the code expires, start sign-in again. The browser may be on a different
device from the Suchi server.

Select the filing system before starting. Suchi binds the flow to the authenticated
actor and starting system; completing it against another system or foreign account
fails. Switching systems discards the browser's pending flow/handoff state.

For API integrations, new-account completion returns `sealed_secret_b64`: an
authenticated server-sealed creation handoff bound to `{actor_id,system_id,credential}`.
Create accepts it only for the same actor/target with current membership, then stores
the ordinary at-rest Microsoft credential. It is **not** arbitrary at-rest ciphertext
that can be copied from another mailbox or flow. The at-rest format below is unchanged.

## Stored credential

Suchi stores a versioned, AEAD-sealed credential envelope containing the
issuing public client ID and an opaque MSAL token cache. The cache can include
access, refresh, and account data required for silent renewal. It is sealed
with `$DATA_DIR/.decrypt-key` before entering SQLite.

Each poll asks MSAL for a valid token and reseals an updated cache when needed.
If tenant policy, consent revocation, or token expiry prevents refresh, the
mailbox reports an authentication error and requires explicit sign-in again.

## Shipped registration

The project registration is configured for:

* personal Microsoft accounts and organizational work or school accounts
* public-client device-code flow
* delegated Exchange `IMAP.AccessAsUser.All`
* automatic MSAL `offline_access` for silent token renewal

The client ID is a public application identifier, not a credential. It is sent
in OAuth requests and is visible in both source and compiled distributions.
Keeping the project-owned ID beside the OAuth implementation gives published
builds a reproducible default and lets ordinary users sign in without Azure
setup. Moving the same value to a generated file or build flag would not make
it secret. The ID can be copied, so the registration does not prove a request
came from an official Suchi binary.

The security boundary is the delegated permission and user or tenant consent,
plus the sealed token cache stored after sign-in. Suchi never ships or requests
a Microsoft client secret. The project limits the registration to delegated
IMAP access and should keep its publisher verified and sign-ins monitored.
Publisher verification identifies who owns the registration; it does not make
the public ID exclusive to official Suchi builds.

Authorization-code flows normally bind a sign-in to a registered redirect URI
and use PKCE to protect the returned authorization code. Device-code flow has no
redirect callback or PKCE exchange. Its protection against remote consent
phishing is the explicit user-initiated flow and the short-lived code entered on
Microsoft's page. Only complete a code that you just requested from your own
Suchi instance. See Microsoft's distinction between
[public and confidential clients](https://learn.microsoft.com/en-us/entra/msal/msal-client-applications).

## Deployment registration

An organization may use its own Entra registration for tenant policy, admin
consent, or deployment-specific naming. This is optional and is configured by
the deployment operator, not through the Suchi UI.

Create the registration in Microsoft Entra:

1. Open **App registrations > New registration**.
2. Choose the required account audience. Select personal plus organizational
   accounts when both must work; a tenant-only deployment may choose its own
   organizational directory.
3. Leave the redirect URI empty.
4. Under **Authentication**, enable public client flows.
5. Under **API permissions**, add delegated
   `IMAP.AccessAsUser.All` from **Office 365 Exchange Online**.
6. Grant tenant admin consent when organization policy requires it.
7. Copy the Application (client) ID. Do not create a client secret. MSAL
   requests `offline_access` automatically during sign-in.

If **Office 365 Exchange Online** is absent in a bare Entra tenant, declare its
delegated permission directly on the app registration:

```sh theme={null}
az ad app permission add \
  --id "<application-client-id>" \
  --api 00000002-0000-0ff1-ce00-000000000000 \
  --api-permissions 652390e4-393a-48de-9484-05f9b1212954=Scope
```

The portal may show the permission UUID instead of its friendly name when the
tenant lacks local Exchange metadata. Type **Delegated** and **Admin consent
required: No** are the expected values.

Set the override before starting Suchi:

```toml theme={null}
# suchi.toml
ingest_imap_oauth_client_id_microsoft = "<application-client-id>"
```

Or set `INGEST_IMAP_OAUTH_CLIENT_ID_MICROSOFT` in the process environment. The
environment wins over the config file. Remove the value to restore Suchi's
shipped registration on the next start.

Precedence is:

1. `INGEST_IMAP_OAUTH_CLIENT_ID_MICROSOFT`
2. `ingest_imap_oauth_client_id_microsoft` in the config file
3. Suchi's shipped registration

This is the Microsoft-specific form of Suchi's documented [configuration
precedence](/config#precedence).

Existing mailboxes keep refreshing with the client ID stored in their
credential envelope after the deployment registration changes. Reauthenticate
a mailbox only when intentionally moving it to another registration.

## Revoke and reauthenticate

**Revoke sign-in** removes the sealed credential from Suchi and disables the
mailbox until it is configured again. To invalidate consent or refresh tokens
at Microsoft as well, remove the application's access from the Microsoft
account or organization portal.

Then start **Sign in with Microsoft** again. Explicit reauthentication uses the
currently active registration.

See [Mail intake](/guides/mail-intake) and Microsoft's documentation for
[public clients](https://learn.microsoft.com/en-us/entra/msal/dotnet/acquiring-tokens/desktop-mobile/device-codes-flow),
[account audiences](https://learn.microsoft.com/en-us/entra/identity-platform/single-and-multi-tenant-apps), and
[IMAP OAuth](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth).