1
注册应用
entra.microsoft.com → 应用程序 → 应用注册 → 新注册
- 名称：
BestTeam，或按贵司命名规范 - 受支持的账户类型：单租户（仅此组织目录中的账户）
- 重定向 URI：留空
在概述页记下 目录(租户) ID 和 应用程序(客户端) ID。
接入配置 · 面向 IT 管理员
Microsoft 365 邮箱接入配置
面向客户 Microsoft 365 租户的管理员。全部配置在贵司租户内完成，约 20 分钟。
约 20 分钟应用级 OAuth，无用户上下文范围限定到一个邮箱
这份文档通常由正在配置 BestTeam 邮箱的同事转发而来。对方手上看的是同一流程的非管理员版本，如需了解他们被要求做什么，可一并查看。
我们申请的是什么
- 权限
- Office 365 Exchange Online → Application →
IMAP.AccessAsApp - 授权方式
- OAuth 2.0 client credentials（应用级）。无用户上下文，不申请任何 delegated 权限
- 协议
- IMAP4 over TLS，
outlook.office365.com:993，SASLXOAUTH2 - 令牌 scope
https://outlook.office365.com/.default- 邮箱范围
- 指定的一个邮箱，由 Exchange Application Access Policy 限定
- 实际用到的操作
SELECT、FETCH、SEARCH，以及往草稿箱APPEND。不打\Deleted标记、不EXPUNGE、不走 SMTP- 重定向 URI
- 无。没有交互式登录，也就没有回调地址
- 入站访问
- 无。连接均由我方主动发起，方向为出站
这不是 basic auth。禁用旧版身份验证、安全默认值、“关闭 IMAP 基本身份验证”等策略均可保持开启，不影响本接入。连接用的是 OAuth bearer token 走
XOAUTH2，正是 Microsoft 为 IMAP 提供的现代身份验证路径。IMAP.AccessAsApp 不是 Graph 的邮件权限。它只是为这个应用打开 IMAP 协议，不授予 Microsoft Graph 邮件 API 的任何访问权，没有Mail.Read / Mail.ReadWrite，也不涉及 Exchange 以外的任何东西。拿到权限之后它做什么
每隔几分钟轮询一次邮箱，读取新邮件，把回复草稿 APPEND 到草稿箱。它不发送：产品中没有 SMTP 客户端，也没有任何 send操作，草稿只有在有人打开 Outlook 点击发送之后，才会离开租户。
邮件正文在写入我方存储之前会先做脱敏。附件按文本解析（PDF、Word、Excel、XML、纯文本），图片不做 OCR。
需要的角色
| 步骤 | 角色 |
|---|---|
| 应用注册 | Application Administrator（或 Global Administrator） |
| 为应用程序权限授予管理员同意 | Global Administrator 或 Privileged Role Administrator |
New-ServicePrincipal、Add-MailboxPermission、New-ApplicationAccessPolicy | Exchange Administrator（或 Global Administrator） |
配置步骤
2
添加权限并授予同意
API 权限 → 添加权限 → 我的组织使用的 API → Office 365 Exchange Online → 应用程序权限 → IMAP → IMAP.AccessAsApp
然后授予管理员同意。默认带的 User.Read（delegated）用不到，按贵司基线要求可以删掉。
确认那一行显示为“已为<租户>授予”。如果租户设有禁止对应用程序权限授予管理员同意的策略，这一步会静默失效，后果是稍后认证失败，而报错与密钥填错时完全一致。
3
创建客户端密码
证书和密码 → 客户端密码 → 新客户端密码（有效期最长 24 个月）
记下值（Value）（不是 Secret ID）和过期日期。值只在创建的那一刻可见。
本接入不支持证书凭据。如果贵司策略禁止使用 client secret，请在开始之前告知我们，越早越好，免得走到这一步才发现。
4
在 Exchange 里注册服务主体并授予邮箱访问
下面用到的 Object ID 是服务主体的对象 ID：Entra ID → 企业应用程序 → 该应用 → 对象 ID。不是应用注册页面上显示的那个对象 ID。
填一次，下面的命令自动替换
无需在此填写 client secret，本页面用不到它。填入的值仅保留在本机浏览器中。
安装模块并连接
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser
Connect-ExchangeOnline -UserPrincipalName <管理员UPN>注册服务主体，授予邮箱访问
New-ServicePrincipal -AppId <应用程序ID> -ServiceId <服务主体对象ID> -DisplayName "BestTeam"
Add-MailboxPermission -Identity <邮箱> -User <服务主体对象ID> -AccessRights FullAccess在 Exchange 已同步过服务主体的租户上，New-ServicePrincipal 会提示“已存在”，属于正常，继续执行即可。
关于 FullAccess
对目标邮箱授予 FullAccess 是 Microsoft 应用级 IMAP 流程的硬性要求，没有更细的邮箱权限能同时满足 IMAP 的 SELECT 与APPEND。该权限只授在一个邮箱上，不是租户级；真正阻止这个应用把权限用到其它邮箱的，是第 5 步。跳过第 5 步，这个权限实际上等同于租户级。
共享邮箱很适合此用途，在常规容量限制内也无需许可证。如果目标邮箱尚未创建，建议直接创建为共享邮箱，而非带许可证的用户邮箱。
5
把范围限定到这一个邮箱
创建访问策略
New-ApplicationAccessPolicy -AppId <应用程序ID> -PolicyScopeGroupId <邮箱> -AccessRight RestrictAccess -Description "BestTeam: single mailbox"验证：目标邮箱 Granted，其它邮箱 Denied
Test-ApplicationAccessPolicy -Identity <邮箱> -AppId <应用程序ID>结束会话
Disconnect-ExchangeOnline如果以邮件启用的安全组来管理更贴合贵司的权限模型，将该组传给 -PolicyScopeGroupId 即可。
策略变更最长需要一小时才同步完成。紧接着进行连接测试若失败，并不说明策略配置有误。
如果贵司已经在用 RBAC for Applications 做这类范围限定，用它替代访问策略是合理的。但本接入只在New-ApplicationAccessPolicy 上验证过，未验证过 RBAC for Applications。若采用该方案，请提前告知，并预留一轮额外的联调。
6
回传四项值
| 值 | 出处 |
|---|---|
| 目录(租户) ID | 第 1 步，概述页 |
| 应用程序(客户端) ID | 第 1 步，概述页 |
| 客户端密码的值 | 第 3 步 |
| 密码过期日期 | 第 3 步 |
外加邮箱的 SMTP 地址。
请不要通过邮件或聊天工具传递那串密码。沿用贵司现有的凭据交接方式即可：密码管理器的分享链接、一次性密文服务，或在通话中口述。密码到我方后以 Fernet 加密存储，密钥不放在数据库里。
过期日期请务必一并提供：我们会记录下来，并在到期前一个月预警。缺少它，到期后的第一个症状是邮箱静默停止处理，而报错与密钥填错时无法区分。
出网地址
只有从我们主机发起的出站连接：
| 目标 | 端口 | 用途 |
|---|---|---|
login.microsoftonline.com | 443 | 获取令牌 |
outlook.office365.com | 993 | IMAP over TLS |
不存在任何进入贵司网络的入站连接，没有本地部署组件，也不会使用贵司的任何服务账号做交互式登录。令牌有效期约一小时，在到期前约一分钟自动刷新。
审计与吊销
- 登录记录：Entra ID → 登录日志 → 服务主体登录，按应用程序 ID 过滤。
- 邮箱操作：如果该邮箱开启了邮箱审计，操作会以服务主体的身份记入统一审计日志。
- 立即吊销：删除客户端密码（最快，现有令牌一小时内失效）、删除应用注册（立即且彻底），或收紧应用程序访问策略。
- 轮换：新增一把密码，把新的“值”发给我们，确认切换成功后再删除旧的。其余步骤均无需重做。
认证失败时
我方报错会区分以下几种情况，因为处理方式完全不同：
| 现象 | 原因 |
|---|---|
| 令牌请求被拒 | 租户 ID、客户端 ID 有误，或密钥错误、已过期。最常见的是把 Secret ID 当成值交了过来 |
令牌拿到了，但 AUTHENTICATE XOAUTH2 被拒 | 第 2 步的管理员同意未完成，第 4 步的两条命令未执行，或第 5 步的访问策略未包含该邮箱 |
| 找不到邮箱 | 该地址不是此租户内的邮箱，或它是通讯组 / Microsoft 365 组，而非邮箱 |
如果贵司启用了针对工作负载标识的条件访问（Conditional Access for workload identities），作用于服务主体的策略会拦掉这个应用的登录。它在服务主体登录日志中表现为条件访问失败，而非凭据失败。动手轮换密钥之前，建议先查看这里。
常被问到的问题
为什么用 IMAP 不用 Graph？
本产品的组织级邮箱接入走的就是 IMAP + XOAUTH2。另外 IMAP.AccessAsApp 的影响面小于 Mail.ReadWrite：它开放的是一个协议，而不是整个 Graph 邮件接口。
能限定到某个文件夹吗？
不能。IMAP 权限与应用程序访问策略都无法细到邮箱以下，邮箱就是最小单位。这也正是建议使用专用共享邮箱，而非个人邮箱的原因。
能用证书代替密钥吗？
当前版本不行，见第 3 步的说明。
删掉访问策略会怎样？
这个应用会重新具备访问租户内所有邮箱的能力，上限即 IMAP.AccessAsApp 授予的范围。请保留该策略。
如有任何不清楚的地方，或某一条被贵司策略拦下，可直接告知向您转交本文档的人，也可邮件联系 admin@bestteam.online。这是很常见的情况，我们宁可调整方案，也不希望贵司为此绕开策略。