实战：注册 Microsoft Graph 应用 | Easy Understand Hermes Agent

这篇教程带你在 Azure 上注册一个“应用身份”，让 Hermes 能自动读取 Teams 会议转录和录制文件——全程不需要人工登录，配置一次就能长期使用。

先搞懂：什么是“应用注册”？

想象你要给 Hermes 办一张公司门禁卡。这张卡属于“机器人”而非某个员工，所以它不需要员工账号密码，只要管理员在后台给它开通权限，它就能自己进出会议室拿资料。

整个过程分六步：办卡（注册应用）、设密码（客户端密钥）、开通门禁权限（Graph API 权限）、管理员签字（管理员同意）、限定活动范围（访问策略）、把卡号密码存进 Hermes 的保险箱（环境变量）。

开始前你需要：一个能产生会议转录的 Microsoft 365 租户（Teams Premium 或含 Teams 许可证）、Azure 门户管理员权限（entra.microsoft.com）。

第 1 步：创建应用注册（办门禁卡）

用管理员账号登录 entra.microsoft.com
进入 身份 → 应用程序 → 应用注册
点击 新注册
填写：
- 名称：Hermes Teams Meeting Pipeline（随意起名）
- 受支持的账户类型：选 仅此组织目录中的账户（单租户）
- 重定向 URI：留空（机器人不需要登录跳转）
点击注册

完成后你会看到应用概览页，立刻复制两个值：

应用程序（客户端）ID → 对应 MSGRAPH_CLIENT_ID
目录（租户）ID → 对应 MSGRAPH_TENANT_ID

第 2 步：创建客户端密钥（设门禁密码）

左侧菜单打开 证书和密码
点击 新客户端密码
说明填 hermes-graph-secret，过期时间按你的轮换策略选（通常 6-24 个月）
点击添加
立即复制“值”列的内容——它只显示这一次！这就是 MSGRAPH_CLIENT_SECRET

⚠️ 注意：“密码 ID”列不是密码，你要的是“值”列。

第 3 步：开通 Graph API 权限（开大门禁权限）

左侧菜单打开 API 权限
点击 添加权限 → Microsoft Graph → 应用程序权限
按需添加下表权限，然后点击 为 <你的租户> 授予管理员同意，状态列应全部变绿勾

做会议纪要必需：

权限	作用
`OnlineMeetings.Read.All`	读取会议元数据（主题、参与者、链接）
`OnlineMeetingTranscript.Read.All`	读取 Teams 生成的会议转录

转录不可用时的备用（可选）：

权限	作用
`OnlineMeetingRecording.Read.All`	下载会议录制做离线语音转文字
`CallRecords.Read.All`	通过呼叫记录反查会议

把纪要发回 Teams 频道时（仅 graph 投递模式需要，用 webhook 可跳过）：

权限	作用
`ChannelMessage.Send`	向频道发消息
`Chat.ReadWrite.All`	向单聊/群聊发消息

不推荐：OnlineMeetings.ReadWrite.All 等更宽泛的权限——用不到就别给。

第 4 步：（强烈推荐）用访问策略限定可用范围

默认情况下，上述权限让应用能读租户内所有会议。开发环境无所谓，生产环境一定要限制。

Microsoft 提供了 Application Access Policy，只能用 PowerShell 配置。在管理员 PowerShell 中运行：

# 创建策略并关联到 Hermes 应用
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "限定 Hermes 只能读取白名单用户的会议"

# 把策略授予指定用户
Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "alice@example.com"

策略生效最长需要 30 分钟，可用 Test-CsApplicationAccessPolicy 验证。生产租户千万别跳过这步。

第 5 步：把凭据写进环境变量

把三个值填入 ~/.hermes/.env：

MSGRAPH_TENANT_ID=<目录租户ID>
MSGRAPH_CLIENT_ID=<应用程序客户端ID>
MSGRAPH_CLIENT_SECRET=<客户端密码值>

然后加固文件权限：

chmod 600 ~/.hermes/.env

第 6 步：验证令牌获取

Hermes 自带冒烟测试，运行：

python -c "
import asyncio
from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Token acquired, length:', len(token))
print(provider.inspect_token_health())
"

成功会打印长令牌和健康信息（cached: True、expires_in_seconds 约 3600）。失败则报错，常见错误对照：

报错	含义	解决
`AADSTS7000215`	密码错误或过期	重新生成密钥并更新 `.env`
`AADSTS700016`	应用 ID 或租户不对	回第 1 步核对
`AADSTS90002`	租户 ID 打错	重新复制目录 ID
调用时 `insufficient_claims`	权限未管理员同意	回第 3 步重新授权

小总结

注册 Graph 应用就像给机器人办一张“受控门禁卡”：注册应用拿 ID、创建密钥当密码、开通最小权限、用访问策略限定范围、存好凭据并验证。密钥会过期，记得在到期前轮换（新建第二个密钥 → 更新 .env → 重启网关 → 验证 → 删除旧密钥）。

下篇预告：凭据验证通过后，下一步是搭建 Webhook 监听器——让 Hermes 能实时收到“会议刚结束”的通知，自动触发转录拉取。我们下篇见！