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

本页目录