Microsoft Teams

通過 Bot Framework 收發消息，入站活動支持 JWT + JWKS 驗證。支持多租戶和單租戶。

🟡 出站就緒，入站 JWT 驗證。通過 Bot Connector REST API 與 Teams 通信。入站活動由 Microsoft 簽名，並通過動態發現的 JWKS 驗證；偽造的 POST 請求將返回 401。

功能概覽

出站文本：通過 Bot Framework Conversation API 發送， POST {serviceUrl}/v3/conversations/{conversationId}/activities，請求體為 {type:"message", text}。支持線程回覆（replyToActivityId）。
入站 Webhook：路徑為 /webhooks/teams。Microsoft 為每條活動附加 JWT 簽名；Minara 通過 OpenID 元數據端點（https://login.botframework.com/v1/.well-known/openidconfiguration）發現 JWKS，並將二者緩存 24 小時。
出站 OAuth 客戶端憑證令牌緩存：TTL 為 1 小時，提前 5 分鐘刷新。
本版本僅支持文本。Adaptive Cards、Office 365 連接器和文件上傳將在後續版本實現。
文本長度上限為 28000 字符。

配置步驟

1. 在 Azure 註冊機器人

在 Azure 門戶創建 Azure Bot 資源（單區域；開發環境選"F0 免費"套餐即可）。
創建完成後，在"Configuration"面板可查看 Microsoft App ID（GUID），並可創建 Client Secret（即 App Password）。二者均需保存。
選擇租戶範圍："Multi Tenant"（租戶 ID 填 common）或"Single Tenant"（填你的 Azure AD 租戶 GUID）。

2. 將機器人接入 Teams

在 Azure Bot 面板選擇"Channels" → "Microsoft Teams"，接受服務條款並啟用。
創建 Teams 應用清單（或使用 Teams 開發者門戶），將其指向機器人的 Microsoft App ID，然後在租戶內側載進行測試。
將機器人添加到團隊或通過測試用戶私聊。首條入站活動會攜帶 Minara 所需的 conversation.id 和 serviceUrl。

3. 設置機器人消息端點

在 Azure Bot 面板選擇"Configuration" → "Messaging endpoint"，將 URL 設置為 https://<your-host>/webhooks/teams。

4. 配置 Minara

minara auth messaging add
# 从列表中选择 `teams`；依次粘贴 App ID、App Password、租户 ID
#（或填 "common"）、默认会话 ID 和 Service URL。

或者直接設置環境變量：

TEAMS_BOT_APP_ID=<bot Microsoft App ID GUID>
TEAMS_BOT_APP_PASSWORD=<bot Microsoft App Password>
TEAMS_BOT_TENANT_ID=common
TEAMS_DEFAULT_CONVERSATION_ID=<conversation id from a captured inbound activity>
TEAMS_DEFAULT_SERVICE_URL=https://smba.trafficmanager.net/teams/

TEAMS_DEFAULT_SERVICE_URL 的上述值為生產多租戶路由。單租戶或主權雲部署時，請替換為你租戶首條入站活動中出現的 serviceUrl。

5. 測試

minara auth messaging test teams

入站 Webhook

Bot Framework 通過 Authorization: Bearer ... 請求頭中的 JWT 對入站活動進行簽名。Minara 驗證以下內容：

字段	期望值
`iss`（簽發方）	`https://api.botframework.com`
`aud`（受眾）	`TEAMS_BOT_APP_ID`（多租戶）或 `TEAMS_BOT_TENANT_ID` GUID（單租戶）
簽名	RS256，密鑰從 `https://login.botframework.com/v1/.well-known/openidconfiguration` 發現
時鐘偏差	±5 分鐘

JWKS 和 OpenID 元數據緩存 24 小時。Microsoft 會定期輪換密鑰；若 kid 未命中，緩存將失效並重新拉取一次。

接受的活動類型：message。其他類型（conversationUpdate、typing、installationUpdate）將被丟棄。

限制與注意事項

serviceUrl 按會話區分。 Bot Framework 文檔要求從每條入站活動中捕獲 serviceUrl 並按會話持久化。如果入站活動中存在 serviceUrl，Minara 會優先使用；環境變量中的默認值僅作為冷推送時的兜底。
多租戶受眾。 將 TEAMS_BOT_TENANT_ID 設為 common 時，機器人接受來自任意租戶的活動，JWT 受眾等於 TEAMS_BOT_APP_ID。單租戶模式下，填寫租戶 GUID，受眾也隨之變為該 GUID。
Adaptive Cards。 暫不支持；機器人目前僅發送純文本。
JWKS 發現需要在首次入站 POST 時訪問網絡。 若 login.botframework.com 被防火牆攔截，驗證將失敗並返回 401。

故障排查

"每條入站請求均返回 401"

宿主機與 Microsoft 之間的時鐘偏差超過 5 分鐘。
TEAMS_BOT_APP_ID 與 Azure 中機器人的 Microsoft App ID 不匹配（常見粘貼錯誤：Azure Bot 同時有 Application ID 和資源 ID，此處需填 Application ID）。
單租戶模式下：TEAMS_BOT_TENANT_ID 與入站 JWT 中的受眾不匹配。

"出站返回 401（令牌端點）"

TEAMS_BOT_APP_PASSWORD 已輪換或被吊銷。請在 Azure Bot 配置面板重新生成 Client Secret。

"會話未找到（出站返回 404）"

默認的 TEAMS_DEFAULT_CONVERSATION_ID 已失效（用戶卸載了機器人，或頻道已刪除）。請從最近一條入站活動中獲取最新的會話 ID。

參考資料

環境變量：TEAMS_*
出站實現：apps/agent/src/messaging/teams.ts
入站規範：apps/agent/src/messaging/inbound/specs/teams.ts
JWT 工具：apps/agent/src/messaging/_shared/jwt-verify.ts
Bot Connector 認證文檔：learn.microsoft.com

本頁目錄