跳到主要内容

注册 Microsoft Graph 应用程序

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

本指南将介绍：

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

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

先决条件​

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

步骤 1：创建应用注册​

  1. 以租户管理员身份登录 entra.microsoft.com。
  2. 导航到标识 → 应用程序 → 应用注册。
  3. 点击新注册。
  4. 填写：
    • 名称： Hermes Teams Meeting Pipeline（或任何你能识别的名称）。
    • 支持的账户类型： 仅此组织目录中的账户（单租户）。
    • 重定向 URI： 留空 —— 仅应用身份验证不需要。
  5. 点击注册。

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

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

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

  1. 在左侧导航中，打开证书和密码。
  2. 点击新客户端密码。
  3. 说明： hermes-graph-secret。过期时间： 选择符合你轮换策略的值（通常为 6-24 个月）。
  4. 点击添加。
  5. 立即复制值列 —— 它只显示一次。该值是 MSGRAPH_CLIENT_SECRET。

密码 ID 列不是密码。你需要的是值列。

步骤 3：授予 Graph API 权限​

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

  1. 在左侧导航中，打开API 权限。
  2. 点击添加权限 → Microsoft Graph → 应用程序权限。
  3. 从下表中添加与你想要流水线执行的操作相匹配的权限。
  4. 添加后，点击为 <你的租户> 授予管理员同意。每个权限的"状态"列应变为绿色复选标记。

转录优先摘要所需权限​

权限应用可以执行的操作
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将消息发布到 1:1 和群组聊天（仅当你设置 chat_id 作为传递目标时）。

不建议使用​

  • OnlineMeetings.ReadWrite.All / Chat.ReadWrite（不带 .All）—— 超出流水线所需范围。
  • 委托权限 —— 流水线使用仅应用（客户端凭据）流程；委托权限在没有用户登录的情况下无法工作。

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

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

Microsoft 为 Teams 提供应用程序访问策略正是用于此目的。该策略仅支持 PowerShell 界面；没有门户 UI。

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

# 创建限定到 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 分钟。使用以下命令验证：

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

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

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

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

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

设置文件权限，以便只有你可以读取密钥：

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('令牌已获取，长度:', 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 权限并再次点击授予管理员同意。

轮换客户端密钥​

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

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

后续步骤​

凭据验证通过后，继续：

  • Webhook 监听器设置 —— 启动接收 Graph 更改通知的 msgraph_webhook 网关平台。
  • 流水线配置 —— 配置 Teams 会议流水线运行时和操作符 CLI。
  • 出站传递 —— 将摘要回传到 Teams 频道或聊天。

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