Microsoft Teams

🟡 アウトバウンド対応・インバウンド 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 クライアントクレデンシャル token キャッシュ：TTL は 1 時間、5 分前に先行リフレッシュします。
• 現時点ではテキストのみ対応。 Adaptive Cards、Office 365 コネクター、ファイルアップロードは今後の対応予定です。
• テキスト上限：28,000 文字。

セットアップ

1. ボットを登録する（Azure）

1. Azure ポータルで Azure Bot リソースを作成します（リージョンは 1 つ。開発用には価格レベル「F0 free」で十分です）。
2. プロビジョニング完了後、「Configuration」ブレードに Microsoft App ID（GUID）が表示されます。Client Secret（App Password）もここで作成できます。両方を保存してください。
3. テナントスコープを決定します。「Multi Tenant」の場合はテナント ID に common を使用し、「Single Tenant」の場合は Azure AD テナントの GUID を使用します。

2. ボットを Teams に接続する

1. 同じ Azure Bot ブレードで「Channels」→「Microsoft Teams」を選択します。利用規約に同意して有効化してください。
2. Teams アプリマニフェストを作成します（または Developer Portal for Teams を使用します）。ボットの Microsoft App ID を指定し、テスト用にテナントへサイドロードします。
3. チームにボットを追加するか、テストユーザーから DM を送信します。最初のインバウンドアクティビティに、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"）・デフォルトの conversation id・service URL を貼り付ける

または環境変数で設定します：

TEAMS_BOT_APP_ID=<ボットの Microsoft App ID GUID>
TEAMS_BOT_APP_PASSWORD=<ボットの Microsoft App Password>
TEAMS_BOT_TENANT_ID=common
TEAMS_DEFAULT_CONVERSATION_ID=<インバウンドアクティビティから取得した conversation id>
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 は以下を検証します：

JWKS と OpenID メタデータは 24 時間キャッシュされます。Microsoft は定期的にキーをローテーションします。kid が一致しない場合はキャッシュを無効化し、1 回だけ再取得します。

受け入れるアクティビティタイプは message のみです。それ以外（conversationUpdate、typing、installationUpdate）は破棄されます。

制限事項・注意点

• serviceUrl は会話ごとに異なります。 Bot Framework のドキュメントによれば、インバウンドアクティビティから serviceUrl を取得し、会話ごとに永続化する必要があります。Minara はインバウンドの serviceUrl がある場合はそちらを優先します。環境変数のデフォルト値は、コールドプッシュ時のブートストラップ用フォールバックにすぎません。
• マルチテナントのオーディエンス。 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（token エンドポイント）」

• TEAMS_BOT_APP_PASSWORD がローテーションまたは失効しています。Azure Bot の設定ブレードで新しい Client Secret を生成してください。

「Conversation not found（アウトバウンドで 404）」

• デフォルトの TEAMS_DEFAULT_CONVERSATION_ID が古くなっています（ユーザーがボットをアンインストールしたか、チャンネルが削除されました）。最近のインバウンドアクティビティから新しい conversation 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