hermes教程-注册 Microsoft Graph 应用程序

先决条件

一个拥有 Teams Premium 或 Teams 许可证的 Microsoft 365 租户，能够生成会议转录和录制文件
对 Azure 门户 entra.microsoft.com 的管理员访问权限
一个可公开访问的 HTTPS 端点，用于接收 Graph 变更通知（稍后在 webhook 监听器步骤中设置）

步骤 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`	读取 Teams 在线会议元数据（主题、参与者、加入 URL）。
`OnlineMeetingTranscript.Read.All`	读取 Teams 生成的会议转录。

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

权限	允许应用执行的操作
`OnlineMeetingRecording.Read.All`	下载 Teams 会议录制文件以进行离线 STT 处理。
`CallRecords.Read.All`	当仅知道加入 URL 时，通过通话记录解析会议。

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

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

权限	允许应用执行的操作
`ChannelMessage.Send`	代表应用在 Teams 频道中发布消息。
`Chat.ReadWrite.All`	在 1:1 和群聊中发布消息（仅当你将 `chat_id` 设置为投递目标时）。

不推荐

OnlineMeetings.ReadWrite.All / Chat.ReadWrite（不带 .All）—— 比管道所需的范围更广。
委托权限 —— 管道使用应用专用（客户端凭据）流程；没有用户登录，委托权限将无法工作。

步骤 4：（推荐）使用应用程序访问策略限定应用范围

默认情况下，像 OnlineMeetings.Read.All 这样的应用程序权限允许应用访问租户中的每个会议。对于合作伙伴演示和开发租户来说，这没问题；但在生产环境中，你几乎肯定希望限制应用可以读取哪些用户的会议。

Microsoft 专门为此提供了 应用程序访问策略。该策略仅通过 PowerShell 界面操作；门户中没有 UI。

在安装了 MicrosoftTeams 模块并已连接（Connect-MicrosoftTeams）的管理员 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"

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

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

powershell

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

如果没有该策略，任何用户的会议都是可读的——这是权限在技术上的授予范围。在生产租户上不要跳过此步骤。

步骤 5：将凭据写入环境文件

将你收集的三个值放入 ~/.hermes/.env：

bash

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

设置文件权限，确保只有你可以读取密码：

bash

chmod 600 ~/.hermes/.env

步骤 6：验证令牌流程

Hermes 附带一个 Graph 身份验证冒烟测试。在你的 Hermes 安装目录中运行：

python

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。失败会产生一个 MicrosoftGraphTokenError，其中包含 Azure 错误代码——最常见的有：

Azure 错误	含义	修复
`AADSTS7000215: Invalid client secret`	密码值不匹配或已过期。	在步骤 2 中生成新密码；更新 `.env`。
`AADSTS700016: Application not found`	`MSGRAPH_CLIENT_ID` 错误或租户错误。	再次检查步骤 1 中的值是否来自同一个应用。
`AADSTS90002: Tenant not found`	`MSGRAPH_TENANT_ID` 拼写错误。	再次从应用概览中复制目录（租户）ID。
调用时（非令牌获取时）出现 `insufficient_claims`	令牌已获取，但 Graph 返回 401/403。	你跳过了步骤 3 的管理员同意，或者添加了权限但未重新同意。重新访问 API 权限并再次点击授予管理员同意。

轮换客户端密码

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

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

后续步骤

凭据验证通过后，继续执行以下操作：

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

这些页面将与添加相应运行时的 PR 一同发布。此凭据设置是一个独立的先决条件，可以提前完成。