Hermes Agent Microsoft Graph 注册：Azure AD 应用配置指南

Teams 会议管道通过 Microsoft Graph 读取会议转录、录制及相关内容，使用的是 仅应用（守护进程）身份认证——无需用户登录，也无需对每场会议进行交互式授权。这要求在 Azure AD 中注册一个应用，并由管理员授予应用程序权限。

本指南将依次介绍：

1. 创建应用注册
2. 创建客户端密钥
3. 授予管道所需的 Graph API 权限
4. 管理员同意这些权限
5. （可选）通过 Application Access Policy 将应用范围限定到特定用户

你需要 租户管理员权限（或让管理员代为授权）才能完成这些操作。请妥善保存过程中收集的值——最终需要写入 ~/.hermes/.env。

前提条件

• 拥有 Microsoft 365 租户，且具备 Teams Premium 或可生成会议转录和录制的 Teams 许可证
• 拥有 entra.microsoft.com 的管理员访问权限
• 拥有一个公网可访问的 HTTPS 端点用于接收 Graph 变更通知（后续在 webhook 监听器步骤中配置）

第 1 步：创建应用注册

1. 以租户管理员身份登录 entra.microsoft.com。
2. 导航至 Identity → Applications → App registrations。
3. 点击 New registration。
4. 填写：
   • Name： Hermes Teams Meeting Pipeline（或任何你能识别的名称）。
   • Supported account types： Accounts in this organizational directory only (Single tenant)。
   • Redirect URI： 留空——仅应用认证不需要此项。
5. 点击 Register。

进入应用概览页后，复制以下两个值：

• Application (client) ID → MSGRAPH_CLIENT_ID
• Directory (tenant) ID → MSGRAPH_TENANT_ID

第 2 步：创建客户端密钥

1. 在左侧导航栏，打开 Certificates & secrets。
2. 点击 New client secret。
3. Description： hermes-graph-secret。Expires： 根据你的轮换策略选择（通常为 6-24 个月）。
4. 点击 Add。
5. 立即复制 Value 列——该值仅显示一次。此值即为 MSGRAPH_CLIENT_SECRET。

Secret ID 列不是密钥本身，你需要的是 Value 列。

第 3 步：授予 Graph API 权限

管道使用的是最小必要的应用程序权限集。只添加你需要的权限；每项权限都会扩大应用在租户范围内的读取范围。

1. 在左侧导航栏，打开 API permissions。
2. 点击 Add a permission → Microsoft Graph → Application permissions。
3. 根据下表添加与管道功能匹配的权限。
4. 添加完成后，点击 Grant admin consent for <your tenant>。Status 列应对每项权限显示绿色对勾。

转录优先摘要所需权限

录制回退所需权限（转录不可用时）

出站摘要投递所需权限（仅 Graph 模式）

如果 platforms.teams.extra.delivery_mode 为 graph，管道将通过 Graph API 将摘要发送到 Teams 频道或聊天。如果你使用 incoming_webhook 投递模式，可跳过这些权限。

不推荐的权限

• OnlineMeetings.ReadWrite.All / Chat.ReadWrite（不带 .All）——权限范围超出管道所需。
• 委派权限（Delegated permissions）——管道使用仅应用（客户端凭据）流程；委派权限在没有用户登录时无法工作。

第 4 步：（推荐）通过 Application Access Policy 限定应用范围

默认情况下，OnlineMeetings.Read.All 等应用程序权限允许应用访问租户中的 每一场 会议。对于合作伙伴演示和开发租户，这没问题；但在生产环境中，你几乎一定需要限制应用能读取哪些用户的会议。

Microsoft 专门为 Teams 提供了 Application Access Policies。该策略仅支持 PowerShell 配置，没有门户 UI。

在安装了 MicrosoftTeams 模块并已连接（Connect-MicrosoftTeams）的管理员 PowerShell 中执行：

# 创建限定到 Hermes 应用的策略
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# 将策略授予管道可读取其会议的特定用户
Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "alice@example.com"

Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "bob@example.com"

策略授予后，传播可能需要最多 30 分钟。使用以下命令验证：

Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "<MSGRAPH_CLIENT_ID>"

如果没有配置此策略，任何 用户的会议都可被读取——这是权限本身的技术授权范围。在生产租户中请勿跳过此步骤。

第 5 步：将凭据写入环境配置文件

将收集到的三个值写入 ~/.hermes/.env：

MSGRAPH_TENANT_ID=<directory-tenant-id>
MSGRAPH_CLIENT_ID=<application-client-id>
MSGRAPH_CLIENT_SECRET=<client-secret-value>

设置文件权限，确保只有你能读取密钥：

chmod 600 ~/.hermes/.env

第 6 步：验证令牌流程

Hermes 内置了 Graph 认证冒烟测试。在你的 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 和接近 3600 的 expires_in_seconds 值。失败时会抛出 MicrosoftGraphTokenError 并附带 Azure 错误码——最常见的如下：

轮换客户端密钥

Azure 客户端密钥有硬性过期时间。在密钥过期之前：

1. 在第 2 步中创建第二个客户端密钥，不要删除第一个。
2. 用新值更新 ~/.hermes/.env 中的 MSGRAPH_CLIENT_SECRET。
3. 重启网关以加载新密钥：hermes gateway restart。
4. 使用上述冒烟测试进行验证。
5. 从 Azure 门户中删除旧密钥。

后续步骤

凭据验证通过后，可继续以下配置：

• Webhook 监听器设置 —— 搭建接收 Graph 变更通知的 msgraph_webhook 网关平台。
• 管道配置 —— 配置 Teams 会议管道运行时和操作 CLI。
• 出站投递 —— 将摘要回传到 Teams 频道或聊天。

以上页面将随对应运行时的 PR 一同发布。本凭据配置是独立的前置步骤，可以提前安全完成。