第 16b 章 客户端、Groupware & CLI 管理:#pIdentity

面向邮件应用的 OAuth 2.1:Thunderbird、Outlook、设备和命令行

nextxch 本身就是 OAuth 2.1 授权服务器:邮件应用在浏览器中通过常规 Webmail 登录(包括 2FA 和通行密钥)进行登录,用户在授权同意页面上确认访问,应用随后获得短期访问令牌和轮换刷新令牌。IMAP、SMTP、POP3 和 ManageSieve 通过 SASL XOAUTH2 和 OAUTHBEARER(RFC 7628)接受令牌,ActiveSync、EWS 和 MAPI 则以 Bearer 方式接受。无浏览器的设备使用设备代码流程(RFC 8628)。也可接受来自 Entra ID 或 Keycloak 的访问令牌。每项授权对用户和管理员均可见,并可随时立即吊销。

运维提示与架构说明

通过"按协议仅限 OAuth / Kerberos"(管理 > 身份源),可针对单个协议和域关闭密码和应用密码,例如 IMAP 和 SMTP 仅允许 OAuth。没有身份源的本地服务器管理员不受此限制,作为紧急访问通道。

命令行:设备代码流程以及使用 XOAUTH2 的 IMAP

预注册的公共客户端 nextxch-cli。用户打开显示的地址,登录并确认代码。

参考 / 配置
# 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_...

设置、默认值与最佳实践

设置 / 位置 说明 默认值 生产环境最佳实践
Einschalten 管理 > 身份源 > OAuth 2.1:"OAuth sign-in enabled"(启用 OAuth 登录)。颁发者为服务器的公共地址。发现端点位于 /.well-known/oauth-authorization-server 和 /.well-known/openid-configuration,签名密钥 (ES256) 位于 /oauth/jwks。 Aus 访问令牌 60 分钟;刷新令牌 90 天未使用即失效,最长 365 天。刷新令牌被使用两次时,将撤销整个授权(防盗用)。
Thunderbird 预注册的公共客户端"thunderbird",支持 PKCE 和环回重定向。Autoconfig (/.well-known/autoconfig) 在密码之后将 OAuth2 作为第二种方式提供。 client_id thunderbird Thunderbird 仅对其内置列表中的服务商使用 OAuth2;对于您自己的服务器,取决于版本。在此之前,请使用 Kerberos/GSSAPI 或应用密码。
Outlook und Entra ID 使用 Entra 来源并启用“接受协议访问令牌”时,nextxch 接受 Entra 访问令牌(通过 JWKS 校验签名、aud、iss(包括 v1 颁发者 sts.windows.net)、有效期、目录)。ActiveSync、EWS 和 MAPI 会通告 "WWW-Authenticate: Bearer"。 aud = api://mail.firma.de Entra:自行注册应用 "nextxch Mail API",应用程序 ID URI 为 api://mail.example.com,并设置一个作用域(例如 Mail.Access)。Outlook for Windows 是否对您自己的服务器使用新式验证,取决于版本和 Autodiscover;在公司网络中,Kerberos 是可靠的方式。
Eigene Anwendungen 由管理员管理的客户端:公共客户端 (PKCE) 或带机密的机密客户端(机密仅显示一次),重定向 URI 精确匹配或使用任意端口的回环地址,支持 code、refresh 和 device code 流程,可选择跳过同意页面。 PKCE S256 Pflicht 范围:mail(所有协议)、单个协议(imap、smtp、pop3、sieve、eas、ews、mapi、dav、jmap)、offline_access、openid、email、profile。
Übersicht und Widerruf 用户可在 Webmail 的“设置 > 安全”中查看已连接的应用,管理员可在“管理 > 身份源”及账户对话框中查看所有授权。撤销后,已签发的访问令牌也会立即失效。 - 管理员重置 AD 密码时,该账户的所有 OAuth 授权都会被自动撤销。