Chapter 16b Clients, Groupware & CLI Admin: #pIdentity

OAuth 2.1 for mail apps: Thunderbird, Outlook, devices and the command line

nextxch is its own OAuth 2.1 authorization server: mail apps sign in in the browser through the normal webmail login (including 2FA and passkeys), the user confirms access on a consent page, the app receives short-lived access tokens and a rotating refresh token. IMAP, SMTP, POP3 and ManageSieve accept the tokens through SASL XOAUTH2 and OAUTHBEARER (RFC 7628), ActiveSync, EWS and MAPI as bearer. Devices without a browser use the device code flow (RFC 8628). Access tokens from Entra ID or Keycloak can be accepted as well. Every grant is visible to user and admin and can be revoked at once.

Operational Tip & Architecture Note

With "OAuth / Kerberos only per protocol" (Admin > Identity sources) passwords and app passwords can be switched off for single protocols and domains, e.g. IMAP and SMTP with OAuth only. A local server admin without a source stays exempt as break-glass access.

Command line: device code flow and IMAP with XOAUTH2

Pre-registered public client nextxch-cli. The user opens the shown address, signs in and confirms the code.

Reference / Configuration

# 1. Request a device code
curl -s https://mail.example.com/oauth/device_authorization \
  -d client_id=nextxch-cli -d "scope=mail offline_access"
# -> {"device_code":"...","user_code":"BCDF-GHJK","verification_uri":"https://mail.example.com/oauth/device",...}

# 2. Open https://mail.example.com/oauth/device in a browser, sign in, confirm code BCDF-GHJK

# 3. Poll every 5 seconds until the token arrives (authorization_pending / slow_down)
curl -s https://mail.example.com/oauth/token -d client_id=nextxch-cli \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d device_code=...

# 4. IMAP with the access token
curl -v --login-options AUTH=XOAUTH2 --oauth2-bearer "$ACCESS_TOKEN" \
  -u anna@example.com imaps://mail.example.com/INBOX

# 5. Refresh (the old refresh token becomes invalid) and revoke
curl -s https://mail.example.com/oauth/token -d client_id=nextxch-cli \
  -d grant_type=refresh_token -d refresh_token=nxrt_...
curl -s https://mail.example.com/oauth/revoke -d client_id=nextxch-cli -d token=nxrt_...

Settings, Default Values & Best Practices

Setting / Location	Description	Default Value	Production Best Practice
`Einschalten`	Admin > Identity sources > OAuth 2.1: "OAuth sign-in enabled". The issuer is the public address of the server. Discovery at /.well-known/oauth-authorization-server and /.well-known/openid-configuration, signing key (ES256) at /oauth/jwks.	`Aus`	Access token 60 minutes, refresh token 90 days unused, maximum 365 days. A refresh token used twice revokes the whole grant (theft protection).
`Thunderbird`	Pre-registered public client "thunderbird" with PKCE and loopback redirect. Autoconfig (/.well-known/autoconfig) offers OAuth2 as second method after the password.	`client_id thunderbird`	Thunderbird uses OAuth2 only for providers in its built-in list; for your own server this depends on the version. Until then use Kerberos/GSSAPI or an app password.
`Outlook und Entra ID`	With an Entra source and "accept access tokens for protocols" nextxch accepts Entra access tokens (signature by JWKS, aud, iss including the v1 issuer sts.windows.net, expiry, directory). ActiveSync, EWS and MAPI announce "WWW-Authenticate: Bearer".	`aud = api://mail.firma.de`	Entra: own app registration "nextxch Mail API" with application ID URI api://mail.example.com and a scope (e.g. Mail.Access). Whether Outlook for Windows uses modern auth against your own server depends on version and Autodiscover; on the company network Kerberos is the reliable way.
`Eigene Anwendungen`	Admin-managed clients: public (PKCE) or confidential with a secret (shown once), redirect URIs exact or loopback with any port, flows code, refresh and device code, optionally without consent page.	`PKCE S256 Pflicht`	Scopes: mail (all protocols), single protocols (imap, smtp, pop3, sieve, eas, ews, mapi, dav, jmap), offline_access, openid, email, profile.
`Übersicht und Widerruf`	Users see their connected apps in webmail under Settings > Security, admins all grants under Admin > Identity sources and in the account dialog. Revoking also ends access tokens already issued at once.	`-`	When an admin resets an AD password, all OAuth grants of the account are revoked automatically.