FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

一次 Mail.Read 授权,应用就能读遍租户所有邮箱

动手实验:在 Exchange 侧把 Graph 应用锁定到一个共享邮箱,再用测试结果向 IT 证明边界。

用 Microsoft Graph 读取客户的 Outlook 邮箱,而不向整个租户开放访问
图片:Uploaded by ClassicMacOSGuy / Public Domain
分享微博

要点速览

  • 应用权限范围极广:没有登录用户时,应用可以访问该权限覆盖的全部数据。
  • 列出邮件时,Mail.ReadBasic.All 是最低的应用权限;需要更多数据就得申请更高权限。
  • RBAC for Applications 能把应用锁定到指定邮箱,最有力的证据是应用在范围外的邮箱上被拒绝。
双轴矩阵:一轴是能读什么(邮件内容或邮件元数据),另一轴是能读谁的邮件(范围内或整个租户)。砖红色高亮的格子是已删除 Entra 授权的带范围角色:可读内容,且仅限范围内。Mail.Read 以及残留同意的角色仍向整个租户开放;Mail.ReadBasic.All 只读邮件元数据,但同样覆盖整个租户。“元数据、范围内”格子为空。
生效权限是两个来源的并集,Entra 中残留的 Mail.Read 同意会抵消范围限制。只有带范围的角色配合删除 Entra 中的所有 Mail 权限,应用才会被锁定到正确的邮箱。

为一个只该读取发票邮箱的连接器授予一次 Mail.Read 管理员同意,应用就能读取租户里的每一个邮箱。rakhesh.com 在 2021 年的一篇文章中描述过这个现实:Graph 只能授予跨所有邮箱的读信权限,要加以限制,必须在 Exchange 侧额外配置。

如果你的智能体需要读取客户的邮件,就要提前准备好 IT 一定会问的问题:“它能读什么?”读完本文,你可以拿测试结果来回答。

要构建什么,需要先准备什么

场景如下:客户希望智能体读取共享邮箱 invoices@,而且只读这一个。你将构建一个无需用户登录即可调用 Graph 的应用,列出邮件,再把应用锁定到这个邮箱。

你需要一个拥有管理员权限的测试租户、两个邮箱(一个在范围内,一个在范围外)、curl、jq,以及一个 Exchange Online PowerShell 会话。先给两个邮箱各发几封邮件。不要在客户的租户上练手。

写代码之前先问一个问题:应用运行时会有用户登录吗?Microsoft 建议,只要委托权限能满足需求,就优先使用委托权限。仅应用访问适合无人值守的后台任务。

第 1 步:注册应用,申请最窄的权限

注册应用,创建凭据,然后添加应用权限 Mail.ReadBasic.All。对列出邮件的 API 来说,这是最低的应用权限;Mail.Read 和 Mail.ReadWrite 都更高。

这个权限服务于第 3 步;到第 4 步你会删除它,改用带范围的权限。在实验环境中,用 secret 最省事;在客户那里,先问清对方的凭据策略再做选择。

应用权限一律需要管理员同意。**检查:**该权限已在租户中获得管理员同意。在自己的实验环境里你自己点一下即可;在客户那里,这是一场必须列入计划的会议。

第 2 步:获取 token

下面的版本直接用原始 HTTP 请求,方便你看清每个参数。它只用于实验,不要原样上线到生产环境。租户的 token 端点见 Get access without a user 文档。.default 范围会打包管理员已同意的全部应用级权限,因此这里不必逐个列出权限。

# 实验用的简便写法:TOKEN_URL 是租户的 token 端点
export TOKEN_URL='<tenant token endpoint>'
export CLIENT_ID='<application id>'
read -rs CLIENT_SECRET

TOKEN=$(curl -s -X POST "$TOKEN_URL" \
  -d "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "scope=https://graph.microsoft.com/.default" \
  -d "grant_type=client_credentials" | jq -r .access_token)

if [ -n "$TOKEN" ] && [ "$TOKEN" != "null" ]; then
  echo "已获取 token"
else
  echo "未获取 token"
fi

**检查:**终端输出 已获取 token。如果没有,去掉 jq 部分重新运行命令,读取错误响应;但绝不要把含有 token 的响应粘贴到聊天或工单里。

第 3 步:读取指定邮箱中的邮件

要读取某个用户的邮件,调用 /users/{id | userPrincipalName}/messages。下面的代码用 $select 只取需要的字段。

这是精简版,只用来确认应用能读到邮件,不是读取整个邮箱的代码;参数细节见 List messages 文档。

export MAILBOX='invoices@test-domain'
URL="https://graph.microsoft.com/v1.0/users/$MAILBOX/messages?\$select=subject,receivedDateTime"

curl -s -H "Authorization: Bearer $TOKEN" "$URL" \
  | jq '{message_count: (.value | length)}'

检查:message_count 大于 0,因为你给这个邮箱发过邮件。把返回的数据和智能体要完成的任务对照一下,这是判断是否需要更高权限的依据。

为什么应用能跑通只算完成了一半

应用能用了,但权限仍然太宽。Microsoft 把应用权限归为高特权权限,因为应用无需任何人登录就能访问和修改数据。它的文档说得很直白:给应用超出需要的权限,是糟糕的安全实践。

下表说明为什么仅靠 Mail.ReadBasic.All 还不能了事。智能体需要更多数据时,你必须申请更高权限,这时邮箱范围就成了必须锁死的环节。

配置 权限级别 谁的邮件
来自 Entra 的 Mail.ReadBasic.All 列出邮件的最低权限 不按邮箱限制
来自 Entra 的 Mail.Read 更高 所有邮箱
带范围的 Application Mail.Read 角色 通过 Exchange RBAC 读信 仅范围内的邮箱

第 4 步:更换权限,把应用锁定到正确的邮箱

现在需求变了:假设智能体还要读取发票 PDF,最低权限不够用了。你必须升级到 Mail.Read,但这次不在 Entra 里授予,而是通过 Exchange 的 Application Mail.Read 角色授予,并绑定一个范围。

Exchange Online 的 RBAC for Applications(面向应用的基于角色的访问控制)把权限与资源范围配对,资源范围决定应用可以访问哪些邮箱。它取代了 Application Access Policies。

陷阱在这里:生效权限是 Entra 授予的权限与 Exchange RBAC 授予的权限的并集。正如 Tony Redmond 在 Practical365 上提醒的,如果 Entra 里还保留着 Mail.Read,RBAC 提供的所有控制都会失效。

用假设的数字算一下:租户有 800 个邮箱,范围里只有 invoices@。Entra 中还保留 Mail.Read 时,800 个邮箱与 1 个邮箱的并集仍是 800 个。撤销同意之后,应用就只剩 1 个邮箱。

所以先清理 Entra。Entra 中残留的任何权限都会叠加到生效权限上,因此第 1 步授予的 Mail.ReadBasic.All 必须删掉,如果曾经加过 Mail.Read,也一并删除:在 Enterprise applications 中打开该应用,撤销管理员同意,再从应用配置中删除这些权限。

**检查:**应用已同意的权限列表中没有任何 Mail 权限。门户的按钮位置可能会变,以这条标准为准。

接下来,准备一个只包含 invoices@ 的管理单元,记下它的 ID;完整流程参考 Microsoft 的 RBAC for Applications 指南。然后填入三个值,运行下面两条命令。

# AppId 和 ObjectId 取自 Enterprise applications 页面
$AppId = '<Application ID>'
$ObjectId = '<Object ID>'
$AdminUnitId = '<admin unit ID>'

New-ServicePrincipal -AppId $AppId -ObjectId $ObjectId
New-ManagementRoleAssignment -App $AppId -Role "Application Mail.Read" -RecipientAdministrativeUnitScope $AdminUnitId

如果客户已经用管理范围(management scope)管理邮箱,把最后一个参数换成 -CustomResourceScope 加该范围的名称。**检查:**两条命令都没有报错。没有报错并不能证明 ID 或范围正确,这要留到第 5 步验证。

第 5 步:证明应用在该被拦的地方被拦住

对两个邮箱分别运行 Test-ServicePrincipalAuthorization。这个 cmdlet 绕过缓存,立即给出结果;而真实应用的权限变更可能需要 30 分钟到 2 小时才生效,取决于应用最近一次使用的时间。

Test-ServicePrincipalAuthorization -Identity $AppId -Resource 'invoices@test-domain'
Test-ServicePrincipalAuthorization -Identity $AppId -Resource 'out-of-scope@test-domain'

**检查:**在每次运行的输出中查找 Application Mail.Read 角色。该角色必须在 invoices@ 上生效,在另一个邮箱上不生效。如果两个都生效,怀疑范围过宽;如果两个都不生效,重新核对 ID 和范围。

权限变更后立即发起的 Graph 调用,无论成功还是失败,都说明不了问题。所以要等缓存窗口过去,再重新运行第 2 步获取新 token。

不要把第 3 步的代码原样拿来做这个测试。它只输出 value 的长度,被拒绝时同样显示 message_count: 0,和空邮箱一模一样。下面的代码保留了 HTTP 状态码和错误码。

RESP=$(mktemp)
for MAILBOX in 'invoices@test-domain' 'out-of-scope@test-domain'; do
  URL="https://graph.microsoft.com/v1.0/users/$MAILBOX/messages?\$top=1&\$select=id"
  STATUS=$(curl -s -o "$RESP" -w '%{http_code}' \
    -H "Authorization: Bearer $TOKEN" "$URL")
  echo "$MAILBOX | HTTP $STATUS | $(jq -r '"message_count=\(.value | length) error=\(.error.code // "none")"' "$RESP")"
done
rm -f "$RESP"

检查:invoices@ 这一行必须是 HTTP 200、message_count=1、error=none。范围外那一行必须显示非 200 的 HTTP 状态码和具体的错误码。如果它显示 HTTP 200 且读到了邮件,回到第 4 步的同意清理环节。

范围外那一行才是关键证据。把确切的 HTTP 状态码和错误码保存下来,交给客户的 IT 团队。

两个让你误以为已经完工的陷阱

第一个陷阱是从 App registrations 页面取 ID,因为你刚在那里注册了应用。那个页面显示的值和 Enterprise applications 不同,用了它们,New-ServicePrincipal 就会出错。

第二个陷阱是认为 Test-ServicePrincipalAuthorization 结果干净就够了。这个 cmdlet 不考虑在 Entra 中单独授予的权限,所以只能反映 RBAC 这一侧。这正是第 5 步真实 Graph 调用测试不能省略的原因。

和客户 IT 团队开会时带什么

应用权限一律需要管理员同意,所以这件事你无法独自完成。开 IT 会议时带一页纸:申请的权限、为什么更低的权限不够用、范围内的邮箱列表、如何撤销访问,以及范围外邮箱返回的 HTTP 状态码和错误码。

这项技能也很适合写进简历。与其写“集成了 Microsoft Graph”,不如写明你把应用限制在了指定邮箱,以及如何验证的。当前线部署工程师(FDE)的岗位描述提到企业数据时,这是一个值得为面试准备的故事。

下次客户问你的智能体能读什么,最好的回答是给他们看它被拒绝的那一次。

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力照抄上周,可能比客户的预测模型更准先建朴素基线,再用模型没见过的数据回测,别让训练集上的误差决定排班。