跳到主要內容

註冊 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 旁邊。此憑據設置是一個獨立的前置條件，可以提前安全地完成。