Skip to main content
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.

​
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:
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:
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. 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 and Microsoft’s documentation for public clients, account audiences, and IMAP OAuth.