🛡

Microsoft Agents 365 SDK の通信と認証を理解する

に公開
Azure
Copilot
Bot Framework
tech

はじめに

Microsoft Agents 365 SDK では、Microsoft Bot Framework における認証設定が大幅に変更されました。この変更内容を理解するには、Azure AI Bot Service を含めて、通信と認証がどのように行われるかを把握しておく必要があります。

対象となるチャネルによってエンドポイントの URL は異なりますが、全体の流れは共通です。ここでは Direct Line を例に、通信の全体像を説明します。全体像は次のとおりです。

クライアントから Azure AI Bot Service への通信

クライアントがチャットを開始すると、Azure AI Bot Service へ要求を送信します。Direct Line の場合、要求 URL は https://directline.botframework.com/v3/directline/conversations です。アクセス トークンは事前に https://directline.botframework.com/v3/directline/tokens/generate から取得しておく必要があります。トークンの例を次に示します。

{
  "bot": "{{bot-name}}",
  "site": "8ABv5Ars...",
  "conv": "Lp3Ykla1...",
  "jti": "8DE58...",
  "nbf": 1769007600,
  "exp": 1769011200,
  "iss": "https://directline.botframework.com/",
  "aud": "https://directline.botframework.com/"
}

クライアントは複数の応答を受信できるよう、WebSocket を使用して Azure AI Bot Service と通信します。

Azure AI Bot Service から Azure Web Apps への通信

Azure AI Bot Service は要求を受信すると、登録されたメッセージング エンドポイントに要求を転送します。メッセージング エンドポイントの URL は https://{{resource-name}}.azurewebsites.net/api/messages です。このときに渡されるアクセス トークンは、次のようになります。

{
  "serviceurl": "https://webchat.botframework.com/",
  "nbf": 1769007600,
  "exp": 1769011200,
  "iss": "https://api.botframework.com",
  "aud": "ff6bd3e5-..."
}

Microsoft Agents 365 SDK では、このアクセス トークンを検証します。検証処理は、AspNetExtensions.cs の AddAgentAspNetAuthentication メソッドで実装されています。

https://github.com/microsoft/Agents/blob/da34f2e7d912893569dae91a31671427b95d90c8/samples/dotnet/quickstart/AspNetExtensions.cs#L82-L225

このメソッドが参照する設定は、appsettings.json の TokenValidation セクションに定義します。ここで Audiences に指定するクライアント ID は、トークンの aud クレームの値と一致している必要があります。

{
  "TokenValidation": {
    "Audiences": [
      "{{client-id}}"
    ],
    "TenantId": "{{tenant-id}}"
  }
}

Azure Web Apps から Azure AI Bot Service への通信

Azure Web Apps からは、既存の要求への単一の応答ではなく、新しい要求を Azure AI Bot Service に送信することで、複数の応答を実現します。要求 URL は、ConversationReference クラスの ServiceUrl プロパティに格納されます。Direct Line の場合、要求 URL は https://directline.botframework.com/v3/directline/conversations です。このときに渡されるアクセス トークンは、次のようになります。

{
  "aud": "https://api.botframework.com",
  "iss": "https://sts.windows.net/{{tenant-id}}/",
  "iat": 1769007600,
  "nbf": 1769007600,
  "exp": 1769011200,
  "aio": "k2ZgYJid...",
  "appid": "7a9090d4-...",
  "appidacr": "1",
  "idp": "https://sts.windows.net/{{tenant-id}}/",
  "idtyp": "app",
  "oid": "c88a3482-...",
  ...
}

Microsoft Agents 365 SDK では、ServiceUrl ごとに異なる認証を設定できます。これは、appsettings.json の ConnectionsMap セクションで指定します。複数のチャネルで異なる認証をする必要がなければ、ServiceUrl にはワイルドカードを指定します。

{
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]  
}

実際の認証情報は Connections セクションで指定します。ここで使用するキー名 (ここでは ServiceConnection) は、ConnectionsMap セクションで指定した値と一致している必要があります。

{
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{client-id}}",
        "ClientSecret": "{{client-secret}}",
        "TenantId": "{{tenant-id}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }
}

おわりに

実際に発行されるアクセス トークンと設定値を比較すると、認証の流れを具体的に把握できます。特にセキュリティに関わる部分なので、仕組みを理解したうえで実装することが重要です。

Discussion