注册 Microsoft Graph 应用程序

Teams 会议流水线使用仅限应用（daemon）身份验证从 Microsoft Graph 读取会议转录、录制及相关产物——无需用户登录，无需每次会议单独交互式授权。这需要一个经过管理员同意、具备应用程序权限的 Azure AD 应用注册。

本指南涵盖以下步骤：

创建应用注册

创建客户端密钥

授予流水线所需的 Graph API 权限

管理员同意这些权限

（可选）通过应用程序访问策略将应用限定到特定用户

完成本指南需要租户管理员权限（或由管理员代为授予同意）。请记录收集到的值——最终需要填入 ~/.hermes/.env。

前提条件

一个具备 Teams Premium 或 Teams 许可证（可生成会议转录和录制）的 Microsoft 365 租户

可访问 Azure 门户 entra.microsoft.com 的管理员权限

一个可公开访问的 HTTPS 端点，用于接收 Graph 变更通知（在后续 webhook 监听器步骤中配置）

步骤 1：创建应用注册

以租户管理员身份登录 entra.microsoft.com。

导航至 Identity → Applications → App registrations。

点击 New registration。

填写以下内容：

Name：Hermes Teams Meeting Pipeline（或任何你能识别的名称）。

**Supported account types：**Accounts in this organizational directory only (Single tenant)。

**Redirect URI：**留空——仅限应用的身份验证不需要此项。

点击 Register。

页面将跳转至应用概览页。复制以下两个值：

Application (client) ID → MSGRAPH_CLIENT_ID

Directory (tenant) ID → MSGRAPH_TENANT_ID

步骤 2：创建客户端密钥

在左侧导航栏中，打开 Certificates & secrets。

点击 New client secret。

Description：hermes-graph-secret。**Expires：**根据你的轮换策略选择合适的值（通常为 6-24 个月）。

点击 Add。

立即复制 Value 列的值——该值仅显示一次。此值即为 MSGRAPH_CLIENT_SECRET。

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

步骤 3：授予 Graph API 权限

流水线使用最小化的应用程序权限集。仅添加所需权限；每项权限都会扩大应用在租户范围内的读取能力。

在左侧导航栏中，打开 API permissions。

点击 Add a permission → Microsoft Graph → Application permissions。

根据下表添加流水线所需的权限。

添加完成后，点击 Grant admin consent for <your tenant>。每项权限的 Status 列应变为绿色对勾。

转录优先摘要所需权限

权限	允许应用执行的操作
`OnlineMeetings.Read.All`	读取 Teams 在线会议元数据（主题、参与者、加入 URL）。
`OnlineMeetingTranscript.Read.All`	读取 Teams 生成的会议转录。

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

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

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

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

权限	允许应用执行的操作
`ChannelMessage.Send`	以应用身份向 Teams 频道发布消息。
`Chat.ReadWrite.All`	向一对一及群组聊天发布消息（仅在将 `chat_id` 设为投递目标时需要）。

不推荐的权限

OnlineMeetings.ReadWrite.All / Chat.ReadWrite（不带 .All）——权限范围超出流水线所需。

委托权限——流水线使用仅限应用（客户端凭据）流程；委托权限在没有用户登录的情况下无法生效。

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

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

Microsoft 专门为 Teams 提供了应用程序访问策略（Application Access Policies）。该策略仅支持 PowerShell 操作，没有门户 UI。

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

# Create a policy scoped to the Hermes app
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# Grant the policy to specific users whose meetings the pipeline may read
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：

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

步骤 6：验证令牌流程

Hermes 内置了 Graph 身份验证冒烟测试。在 Hermes 安装目录下执行：

成功执行后将打印一个较长的 token（令牌）字符串，以及一个健康状态字典，其中 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` 存在拼写错误。	重新从应用概览页复制 Directory (tenant) ID。
`insufficient_claims`（调用时报错，非获取令牌时）	令牌获取成功，但 Graph 返回 401/403。	跳过了步骤 3 的管理员同意，或添加权限后未重新同意。重新进入 API permissions 并点击 Grant admin consent。

轮换客户端密钥

Azure 客户端密钥有固定的过期时间。在密钥过期前：

在步骤 2 中创建第二个客户端密钥，不要删除第一个。

用新值更新 ~/.hermes/.env 中的 MSGRAPH_CLIENT_SECRET。

重启 gateway 以使新密钥生效：hermes gateway restart。

使用上述冒烟测试进行验证。

在 Azure 门户中删除旧密钥。

后续步骤

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

Webhook 监听器配置——部署接收 Graph 变更通知的 msgraph_webhook gateway 平台。

流水线配置——配置 Teams 会议流水线运行时及操作员 CLI。

出站投递——将摘要回传至 Teams 频道或聊天。

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

"注册 Microsoft Graph 应用程序"

注册 Microsoft Graph 应用程序#

前提条件#

步骤 1：创建应用注册#

步骤 2：创建客户端密钥#

步骤 3：授予 Graph API 权限#

转录优先摘要所需权限#

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

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

不推荐的权限#

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

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

步骤 6：验证令牌流程#

轮换客户端密钥#

后续步骤#