跳到主要内容

注册 Microsoft Graph 应用程序

Teams 会议管道使用仅应用（守护程序）身份验证从 Microsoft Graph 读取会议转录、录音和相关工件——无需用户登录，也无需针对每个会议进行交互式同意。这需要在 Azure AD 中注册一个具有管理员同意的应用程序权限的应用程序。

本指南将逐步介绍：

  1. 创建应用程序注册
  2. 创建客户端密码
  3. 授予管道所需的 Graph API 权限
  4. 对这些权限进行管理员同意
  5. （可选）使用应用程序访问策略将应用程序范围限定为特定用户

你需要租户管理员权限（或由管理员代表你授予同意）才能完成此操作。请收藏你收集的值——最后需要将它们放入 ~/.hermes/.env 中。

先决条件​

  • 一个 Microsoft 365 租户，具有 Teams Premium 或能生成会议转录和录音的 Teams 许可证
  • 对 entra.microsoft.com 上的 Azure 门户的管理员访问权限
  • 一个可公开访问的 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（重定向 URI）：留空——仅应用身份验证不需要此项。
  5. 点击 Register（注册）。

你将进入应用程序的概述页面。复制两个值：

  • Application (client) ID（应用程序（客户端）ID）→ MSGRAPH_CLIENT_ID
  • Directory (tenant) ID（目录（租户）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（密码 ID）列不是密码。你需要的是 Value（值）列。

步骤 3：授予 Graph API 权限​

管道使用最小可行的应用程序权限集。仅添加你需要的内容；每增加一个权限都会扩大应用程序可以在整个租户中读取的范围。

  1. 在左侧导航栏中，打开 API permissions（API 权限）。
  2. 点击 Add a permission（添加权限）→ Microsoft Graph → Application permissions（应用程序权限）。
  3. 从下表中添加与你想让管道执行的操作相匹配的权限。
  4. 添加后，点击 Grant admin consent for <your tenant>（为 <你的租户> 授予管理员同意）。状态列应为每个权限显示绿色对勾。

基于转录的摘要所需​

权限允许应用程序执行的操作
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向一对一和群聊发布消息（仅当你将 chat_id 设置为交付目标时）。
  • OnlineMeetings.ReadWrite.All / Chat.ReadWrite（不带 .All）——比管道所需的范围更广。
  • 委派权限——管道使用仅应用（客户端凭据）流；如果没有用户登录，委派权限将无法工作。

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

Microsoft 为此专门提供了 Teams 的应用程序访问策略。该策略仅通过 PowerShell 配置；没有门户 UI。

在安装了 MicrosoftTeams 模块并已连接 (Connect-MicrosoftTeams) 的管理员 PowerShell 中：

# 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：将凭据写入你的 Env 文件​

将收集的三个值放入 ~/.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 值。失败时会产生带有 Azure 错误代码的 MicrosoftGraphTokenError — 最常见的错误如下：

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

轮换客户端密钥​

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

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

后续步骤​

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

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

这些页面位于添加相应运行时的 PR 旁边。此凭据设置是一个独立的前置条件，可以提前安全地完成。