<!-- Source: https://hermesbible.com/docs/guides/microsoft-graph-app-registration -->

Teams 會議管線使用 僅應用程式（背景服務）認證從 Microsoft Graph 讀取會議逐字稿、錄音和相關產品 — 無需使用者登入，無需每次會議的互動式同意。這需要一個具有管理員同意的應用程式權限的 Azure AD 應用程式註冊。

本指南涵蓋：

1. 建立應用程式註冊
2. 建立客戶端密鑰
3. 授予管線所需的 Graph API 權限
4. 管理員同意這些權限 5.（選擇性）使用應用程式存取原則將應用程式限定於特定使用者

你需要租戶管理員權限（或由管理員代你授予同意）才能完成此操作。將你收集的值加入書籤 — 它們最後會進入 ~/.hermes/.env。

前置需求

• 一個具有 Teams Premium 或能產生會議逐字稿和錄音的 Teams 授權的 Microsoft 365 租戶
• 在 entra.microsoft.com 的 Azure 入口網站管理員存取權限
• 一個公開可達的 HTTPS 端點用於 Graph 變更通知（稍後在 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. 新增後，按一下 為 <your tenant> 授予管理員同意。狀態欄應該為每個權限翻轉為綠色勾號。

逐字稿優先摘要所需

錄音備用所需（當逐字稿不可用時）

出站摘要傳遞所需（僅限 Graph 模式）

如果 platforms.teams.extra.delivery_mode 為 graph，管線透過 Graph API 將摘要發佈到 Teams 頻道或聊天室。如果你使用 incoming_webhook 傳遞模式，請跳過這些。

不建議

• OnlineMeetings.ReadWrite.All / 不含 .All 的 Chat.ReadWrite — 比管線所需更廣泛。
• 委派權限 — 管線使用僅應用程式（客戶端憑證）流程；委派權限在沒有使用者登入的情況下無法運作。

步驟 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 "Restrict Hermes meeting pipeline to allow-listed users"

# 將原則授予管線可以讀取其會議的特定使用者
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=<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 客戶端密鑰有硬性到期時間。在你的到期之前：

1. 在步驟 2 中建立第二個客戶端密鑰，不刪除第一個。
2. 用新值更新 ~/.hermes/.env 中的 MSGRAPH_CLIENT_SECRET。
3. 重啟閘道以使新密鑰生效：hermes gateway restart。
4. 使用上述煙霧測試驗證。
5. 從 Azure 入口網站刪除舊密鑰。

下一步

一旦憑證驗證通過，繼續：

• Webhook 監聽器設定 — 建立接收 Graph 變更通知的 msgraph_webhook 閘道平台。
• 管線設定 — 設定 Teams 會議管線運行時和操作員 CLI。
• 出站傳遞 — 將摘要回傳到 Teams 頻道或聊天室。

這些頁面與新增對應運行時的 PR 同步發佈。此憑證設定是獨立的前置需求，可以安全地提前完成。

---

---

從 OpenClaw 遷移