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

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

原文: https://fdetimes.net/zh/guides/microsoft-graph-read-one-outlook-mailbox/

为一个只该读取发票邮箱的连接器授予一次 `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](https://learn.microsoft.com/en-us/graph/auth-v2-service) 文档。`.default` 范围会打包管理员已同意的全部应用级权限，因此这里不必逐个列出权限。

```bash
# 实验用的简便写法：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](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0) 文档。

```bash
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 指南](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac)。然后填入三个值，运行下面两条命令。

```powershell
# 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 小时才生效，取决于应用最近一次使用的时间。

```powershell
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 状态码和错误码。

```bash
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）的岗位描述提到企业数据时，这是一个值得为面试准备的故事。

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

**本周动手试试:**

- 搭建一个有两个邮箱的测试租户，跑完每一步，记录范围外邮箱返回的 HTTP 状态码和错误码。
- 为一个假设场景写一页权限申请：申请哪个权限、为什么、哪些邮箱、如何撤销。
- 在测试租户中，分别在 Entra 同意仍保留时和删除之后运行第 5 步的测试，记录范围外邮箱上的差异。

## 信源

- [Get access without a user - Microsoft Graph | Microsoft Learn](https://learn.microsoft.com/en-us/graph/auth-v2-service)

- [Overview of Microsoft Graph permissions - Microsoft Graph | Microsoft Learn](https://learn.microsoft.com/en-us/graph/permissions-overview)

- [List messages - Microsoft Graph v1.0 | Microsoft Learn](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0)

- [Role Based Access Control for Applications in Exchange Online | Microsoft Learn](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac)

- [Microsoft Launches Role-Based Access Control for Applications](https://practical365.com/?p=57685)

- [Limit app registration to specific mailbox - rakhesh.com](https://rakhesh.com/azure/limit-app-registration-to-specific-mailbox/)
