實戰：註冊 Microsoft Graph 應用

這篇教學帶你在 Azure 上註冊一個「應用身分」，讓 Hermes 能自動讀取 Teams 會議轉錄和錄製檔案——全程不需要人工登入，設定一次就能長期使用。

---

先搞懂：什麼是「應用註冊」？

想像你要給 Hermes 辦一張公司門禁卡。這張卡屬於「機器人」而非某個員工，所以它不需要員工帳號密碼，只要管理員在後台給它開通權限，它就能自己進出會議室拿資料。

整個過程分六步：辦卡（註冊應用）、設密碼（用戶端密鑰）、開通門禁權限（Graph API 權限）、管理員簽字（管理員同意）、限定活動範圍（存取策略）、把卡號密碼存進 Hermes 的保險箱（環境變數）。

開始前你需要：一個能產生會議轉錄的 Microsoft 365 租戶（Teams Premium 或含 Teams 授權）、Azure 入口網站管理員權限（entra.microsoft.com）。

---

第 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. 按需新增下表權限，然後點擊 為 <你的租戶> 授予管理員同意，狀態欄應全部變綠勾

做會議紀要必需：

權限	作用
OnlineMeetings.Read.All	讀取會議中繼資料（主題、參與者、連結）
OnlineMeetingTranscript.Read.All	讀取 Teams 產生的會議轉錄

轉錄不可用時的備用（可選）：

權限	作用
OnlineMeetingRecording.Read.All	下載會議錄製做離線語音轉文字
CallRecords.Read.All	透過通話記錄反查會議

把紀要發回 Teams 頻道時（僅 graph 投遞模式需要，用 webhook 可跳過）：

權限	作用
ChannelMessage.Send	向頻道發訊息
Chat.ReadWrite.All	向單聊/群聊發訊息

不推薦：OnlineMeetings.ReadWrite.All 等更寬泛的權限——用不到就別給。

第 4 步：（強烈推薦）用存取策略限定可用範圍

預設情況下，上述權限讓應用程式能讀租戶內所有會議。開發環境無所謂，生產環境一定要限制。

Microsoft 提供了 Application Access Policy，只能用 PowerShell 設定。在管理員 PowerShell 中執行：

# 建立策略並關聯到 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"

策略生效最長需要 30 分鐘，可用 Test-CsApplicationAccessPolicy 驗證。生產租戶千萬別跳過這步。

第 5 步：把憑證寫進環境變數

把三個值填入 ~/.hermes/.env：

MSGRAPH_TENANT_ID=<目錄租戶ID>
MSGRAPH_CLIENT_ID=<應用程式用戶端ID>
MSGRAPH_CLIENT_SECRET=<用戶端密碼值>

然後加固檔案權限：

chmod 600 ~/.hermes/.env

第 6 步：驗證權杖取得

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、expires_in_seconds 約 3600）。失敗則報錯，常見錯誤對照：

報錯	含義	解決
AADSTS7000215	密碼錯誤或過期	重新產生密鑰並更新 .env
AADSTS700016	應用程式 ID 或租戶不對	回第 1 步核對
AADSTS90002	租戶 ID 打錯	重新複製目錄 ID
呼叫時 insufficient_claims	權限未管理員同意	回第 3 步重新授權

---

小總結

註冊 Graph 應用就像給機器人辦一張「受控門禁卡」：註冊應用程式拿 ID、建立密鑰當密碼、開通最小權限、用存取策略限定範圍、存好憑證並驗證。密鑰會過期，記得在到期前輪換（建立第二個密鑰 → 更新 .env → 重新啟動閘道 → 驗證 → 刪除舊密鑰）。

---

下篇預告：憑證驗證通過後，下一步是搭建 Webhook 監聽器——讓 Hermes 能即時收到「會議剛結束」的通知，自動觸發轉錄拉取。我們下篇見！

---