ご利用のエージェントで認証を構成する

.NET エージェント SDK Microsoft Authentication Library (MSAL) パッケージは、Microsoft 365 エージェント SDK セルフホステッド エージェントからエージェント クライアントと外部サービス向けのアクセス トークンを作成するユーティリティです。

Microsoft.Agents.Athentication.Msal パッケージは、コア認証プロバイダーである MsalAuth クラスを提供します。 これは、以下の種類の認証情報に対して構成できます。

• クライアント シークレットを使用したシングルテナントとクライアント シークレットを使用したマルチテナント
• サムプリントを使用したクライアント証明書
• サブジェクト名を使用したクライアント証明書 (SN+I を含む)
• ユーザー割り当てマネージド ID
• システム割り当てマネージド ID
• フェデレーション資格情報
• ワークロード ID

認証パッケージをインストールする

NuGet から MSAL 認証パッケージをインストールする

dotnet add package Microsoft.Agents.Authentication.Msal

シングルテナントとマルチテナント

クライアント シークレット認証は、シングルテナント構成とマルチテナント構成の両方をサポートします。

接続の構成

MSAL 認証パッケージを使用すると、Agents Framework ホスティング エンジンで複数の異なるクライアントを作成および使用できます。 MSAL 認証パッケージでは、アプリケーション構成ファイル内で複数の接続構成を指定できます。 各接続構成ごとに、外部サービスや他のエージェントとの通信をサポートする名前付き認証クライアントを作成できます。

認証の種類ごとの環境変数

エージェントは実行時に環境変数から MSAL 構成を取得します。

以下のセクションでは、MSAL 認証でサポートされている各認証の種類に対する必須および任意の構成設定と、各種類の構成スニペットの例について説明します。

クライアント シークレットを使用したシングル テナント

クライアント シークレットで認証するシングルテナント接続を構成するには、これらの設定を使用します。

以下は、シングルテナント ClientSecret 向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

クライアント シークレットを使用したマルチテナント

クライアント シークレットで認証するマルチテナント接続を構成するには、これらの設定を使用します。

以下は、クライアント シークレットを使用したマルチテナント向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "ClientId": "{{BOT_ID}}",
        "ClientSecret": "{{BOT_SECRET}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
            "https://api.botframework.com/.default"
          ],
      }
    }
  }

ユーザー割り当てマネージド ID

ユーザー割り当てマネージド ID を使用してトークン取得を構成するには、これらの設定を使用します。

以下は、ユーザー割り当てマネージド ID 向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "UserManagedIdentity",
        "ClientId": "{{BOT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

システム割り当てマネージド ID

SystemManagedIdentity を使用すると、エージェントは指定されたクライアント ID を無視し、システム割り当てマネージド ID を使用します。

以下は、システム割り当てマネージド ID 認証の種類向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "SystemManagedIdentity",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

フェデレーション資格情報

フェデレーション資格情報をアクセス トークンと交換する接続を構成するには、これらの設定を使用します。

以下は、Federated Credentials 向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "FederatedCredentials",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedClientId": "{{BOT_FEDERATED_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

ワークロード ID

フェデレーション トークン ファイルを使用したワークロード ID 認証を構成するには、これらの設定を使用します。

以下は、シングルテナント WorkloadIdentity 向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  }

オプションのフェデレーション認証、またはワークロード ID クライアント アサーション オプション

フェデレーテッド認証情報やワークロード ID フローのクライアント アサーション コンテンツをカスタマイズするには、これらのオプション設定を使用します。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "WorkloadIdentity",
        "ClientId": "{{BOT_ID}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "FederatedTokenFile": "{{BOT_FEDERATED_TOKENFILE}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ],
        "AssertionRequestOptions": {
            "ClientId": null,
            "TokenEndpoint": null,
            "Claims": null,
            "ClientCapabilities": null,
        }
      }
    }
  }

サブジェクト名を使用した証明書 (SN+I を含む)

証明書のサブジェクト名 (SN+I シナリオを含む) による証明書ベースの認証を構成するには、これらの設定を使用します。

以下は、Subject Name および Issuer (SNI) にサブジェクト名を使用し、マルチテナント構成に対応した証明書の設定例です:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

以下は、SN+I とシングルテナント環境における「Certificate Subject Name」の設定例です:

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "CertificateSubjectName",
        "ClientId": "{{BOT_ID}}",
        "CertSubjectName": "{{BOT_CERT_SUBJECTNAME}}",
        "SendX5C": true,
        "AuthorityEndpoint": "https://login.microsoftonline.com/{{BOT_TENANT_ID}}",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

サムプリントを使用したクライアント証明書

証明書サムプリントによる証明書ベースの認証を構成するには、これらの設定を使用します。

以下は、証明書サムプリントを使用した証明書向けの appsettings の例です。

  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "Certificate",
        "ClientId": "{{BOT_ID}}",
        "CertThumbprint": "{{BOT_CERT_THUMBPRINT}}",
        "AuthorityEndpoint": "https://login.microsoftonline.com/botframework.com",
        "Scopes": [
          "https://api.botframework.com/.default"
        ]
      }
    }
  },

MSAL の既定の構成のプロバイダー

セットアップを容易にするため、MSAL の既定設定をエージェントに追加するサービス プロバイダー拡張機能を提供します。

以下は、Program.cs クラスにおける ASP.NET コア ホスト向けの既定の MSAL 構成プロバイダーの例です。

これは登録済みの IConnections インスタンスによって管理されています。 AddAgent を使用すると、IConnections インスタンスが既定で追加されます。

// Register your AgentApplication
builder.AddAgent<MyAgent>();

ただし、AddAgent を使用していない場合は、IConnections インスタンスを明示的に登録する必要があります。

    // Add Connections object to access configured token connections.
    builder.Services.AddSingleton<IConnections, ConfigurationConnections>();

その他の MSAL 構成オプション

Microsoft Entra Identity からトークンを取得するための一般的な設定を制御する、いくつかの共有構成オプションがあります。

これらの設定は次のとおりです:

MSAL 要求のタイムアウト、再試行動作、ログの詳細の制御を行うには、以下の共有設定を使用します。

これらの設定は、MSAL 認証プロバイダーを使用して作成されるすべてのクライアントと共有されます。 これらの設定は、IConfiguration リーダーによって、"MSALConfiguration" という名前の構成セクションから読み込まれることを想定しています。

以下は、appsettings.json ファイル内のエントリの例です。

{
  "MSALConfiguration": {
    "MSALEnabledLogPII": "true",
    "MSALRequestTimeout": "00:00:40",
    "MSALRetryCount": "1"
  },
}

この場合、この設定ブロックは、MSAL プロバイダーで作成されたすべての MSAL クライアントに対し、個人データのログ記録を有効化し、タイムアウトを 40 秒に設定し、再試行回数を 1 に減らすよう指示します。

この拡張機能は、IConfiguration オブジェクト内で "MSALConfiguration" という名前の構成セクションを検索し、そこから MSAL 構成オブジェクトを作成します。

MSALConfig セクションが 見つからない 場合、既定値を使用して MSAL 構成オブジェクトを作成します。

    // Add default agent MsalAuth support
    builder.Services.AddDefaultMsalAuth(builder.Configuration);

    // Register your AgentApplication
    builder.AddAgent<MyAgent>();

認証のログ記録のサポート

MSAL 認証システムでは、トークン取得のトラブルシューティングが必要な場合に備え、利用統計情報統合の認証フローを個別にログ記録できます。

ログ記録を有効にするには、アプリケーションの appsettings に Microsoft.Agents.Authentication.Msal のエントリを追加し、接続に対するトークン操作を報告する ILogger を設定します。 MSALEnabledLogPII オプションを追加すると、接続の個人情報も含まれます。

以下は、この場合のログ記録ブロックの例です。

  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.Agents": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Agents.Authentication.Msal": "Trace"
    }
  }

この場合、Microsoft.Agents.Authentication.Msal を含む複数のモジュールでログ記録が有効化されており、MSAL のトレースレベルは「Trace」に設定されています。

JavaScript SDK には、ターゲット チャネルにアクティビティを送信するための JSON Web Token (JWT) を取得するために、AuthenticationProvider が必要です。 詳細については、「Microsoft ID プラットフォームのアクセス トークン」を参照してください。

@microsoft/agents-hosting パッケージは、Microsoft Authentication Library (MSAL) に基づく既定の認証プロバイダーを提供します。 これは、以下の認証の種類に対して構成できます。

• クライアント シークレットを使用したシングル テナント
• クライアント シークレットを使用したマルチテナント
• ユーザー マネージド ID
• システム マネージド ID
• フェデレーション資格情報
• ワークロード ID
• 証明書

認証パッケージをインストールする

npm から MSAL 認証パッケージをインストールします。

npm install @microsoft/agents-hosting

シングルテナントとマルチテナント

クライアント シークレットとクライアント証明書認証は、シングルテナント構成とマルチテナント構成の両方をサポートします。

ユーザー割り当てマネージド ID、システム マネージド ID、ェデレーション資格情報、およびワークロード ID は、シングルテナント構成のみをサポートします。

接続の構成

MSAL 認証ライブラリを使用すると、Agents Framework ホスティング エンジンで複数の異なるクライアントを作成および使用できます。 MSAL 認証ライブラリを使用して、アプリケーション構成ファイル内で複数の接続構成を指定できます。 各接続構成ごとに、外部サービスや他のエージェントとの通信を可能にする名前付き認証クライアントを作成できます。

以下のセクションでは、MSAL 認証プロバイダーでサポートされる各認証の種類の必須および任意の構成設定について説明します。 また、各認証の種類の構成スニペットの例も紹介します。

認証の種類ごとの環境変数

エージェントはヘルパー関数 loadAuthConfigFromEnv(): AuthConfiguration を用いて、実行時に環境変数から MSAL 構成を取得します。 CloudAdapter は AuthConfiguration で初期化されます。

接続設定は CONNECTIONS__<CONNECTION_NAME>__SETTINGS__<PROPERTY> の形式を使用します。

AUTHTYPE が存在する場合、SDK はその値を使ってトークン取得フローを選択します。 AUTHTYPE が省略されている場合、SDK はレガシ動作に切り替え、構成された資格情報プロパティから認証フローを自動的に判断します。

クライアント シークレットを使用したシングル テナント

クライアント シークレットで認証するシングルテナント接続を構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

クライアント シークレットを使用したシングル テナントは、ローカル開発に推奨される構成です。

クライアント シークレットを使用したマルチテナント

クライアント シークレットを使用するマルチテナント シナリオでは、認証エンドポイントを botframework.com テナントに設定します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

UserManagedIdentity

これらの設定を使用して、ユーザー割り当てマネージド ID によるトークン取得を構成します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

マネージド IDは、運用環境シナリオで推奨される構成です。 詳細については、Azure リソースのマネージド ID の概要に関するページをご覧ください。

SystemManagedIdentity

認証の種類 SystemManagedIdentity を使用する場合、クライアント ID は無視され、サービスのシステム マネージド ID が使用されます。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

FederatedCredentials

フェデレーション資格情報を通じて認証するシングルテナント アプリを構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=FederatedCredentials
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FICCLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

詳細については フェデレーション ID 資格情報を使用した認証 を参照してください。

WorkloadIdentity

Microsoft Entra ワークロード ID を通じてトークン取得を構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=WorkloadIdentity
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/{tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__FEDERATEDTOKENFILE=/var/run/secrets/azure/tokens/azure-identity-token
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

クライアント証明書を使用したシングルテナント

クライアント証明書を使用して認証を行うシングルテナント接続を構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

クライアント証明書を使用したマルチテナント

クライアント証明書を使用するマルチテナント シナリオでは、認証エンドポイントを botframework.com テナントに設定します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=Certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__SCOPE=https://api.botframework.com

Azure Bot Framework SDK との後方互換性

Azure Bot Framework SDK と同じフォーマットを使用して構成を読み込むには、loadPrevAuthConfigFromEnv(): AuthConfiguration を使用してください。

既存の Bot Framework SDK 構成を移行する際は、これらのレガシ設定名を使用します。

MicrosoftAppTenantId={tenant-id-guid}
MicrosoftAppId={app-id-guid}
MicrosoftAppPassword={app-registration-secret}

カスタム認証プロバイダー

カスタマイズされた認証プロバイダーを必要とするユーザーは、次のインターフェースを実装できます。

export interface AuthProvider {
  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
}

例として、@azure/identity を使用して AuthProvider を実装します。

import { EnvironmentCredential } from "@azure/identity"
import { AuthProvider, AuthConfiguration } from "@microsoft/agents-hosting"
class DevTokenProvider implements AuthProvider {
  async getAccessToken(authConfig: AuthConfiguration): Promise<string> {
    const id = new EnvironmentCredential()
    const tokenResponse = await id.getToken("https://api.botframework.com/.default")
    return tokenResponse.token
  }

DevTokenProvider を使用して CloudAdapterをインスタンス化するには

const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

amework.com/.default") return tokenResponse.token }

To instantiate the `CloudAdapter` by using the `DevTokenProvider`

```ts
const adapter = new CloudAdapter(authConfig, new DevTokenProvider())

Python エージェント SDK Microsoft Authentication Library (MSAL) パッケージは、Microsoft 365 エージェント SDK セルフホステッド エージェントからエージェント クライアントと外部サービス向けのアクセス トークンを作成するユーティリティです。

microsoft-agents-authentication-msal パッケージは、コア認証プロバイダーである MsalAuth クラスを提供します。 これは、以下の種類の認証情報に対して構成できます。

• クライアント シークレット
• クライアント証明書
• ユーザー割り当てマネージド ID
• システム割り当てマネージド ID

認証パッケージをインストールする

PyPI から MSAL 認証パッケージをインストールします。

pip install microsoft-agents-authentication-msal

シングルテナントとマルチテナント

クライアント シークレットとクライアント証明書認証は、シングルテナント構成とマルチテナント構成の両方をサポートします。

ユーザー割り当てマネージド ID とシステム割り当てマネージド ID は、シングルテナント構成のみをサポートします。

接続の構成

MSAL 認証ライブラリを使用すると、Agents Framework ホスティング エンジンで複数の異なるクライアントを作成および使用できます。 各接続構成ごとに、外部サービスや他のエージェントとの通信をサポートするための名前付き認証クライアントが作成されます。

ネストされた設定には、二重アンダースコア (__) の命名規則を使用した環境変数による構成を提供します。 MsalConnectionManagerクラスは環境変数を読み込んで、各接続名ごとに AgentAuthConfiguration インスタンスを構築します。

認証の種類ごとの環境変数

エージェントは、実行時にヘルパー関数 load_configuration_from_env() を使用して、環境変数から MSAL 構成を取得します。

以下のセクションでは、サポートされている各認証の種類ごとに必要な構成設定について説明し、各種類の環境変数スニペットの例を紹介します。

クライアント シークレットを使用したシングル テナント

クライアント シークレットで認証するシングルテナント接続を構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}

クライアント シークレットを使用したシングル テナントは、ローカル開発に推奨される構成です。

クライアント シークレットを使用したマルチテナント

クライアント シークレットを使用するマルチテナント シナリオでは、認証エンドポイントを botframework.com テナントに設定します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=ClientSecret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET={app-registration-secret}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

ユーザー割り当てマネージド ID

ユーザー割り当てマネージド ID を使用してトークン取得を構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={managed-identity-client-id}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=UserManagedIdentity

マネージド IDは、運用環境シナリオで推奨される構成です。 詳細については、Azure リソースのマネージド ID の概要に関するページをご覧ください。

システム割り当てマネージド ID

認証の種類 SystemManagedIdentity を使用する場合、クライアント ID は無視され、サービスのシステム マネージド ID が使用されます。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=SystemManagedIdentity

クライアント証明書を使用したシングル テナント

クライアント証明書を使用して認証を行うシングルテナント接続を構成するには、これらの設定を使用します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID={tenant-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}

クライアント証明書を使用したマルチテナント

クライアント証明書を使用するマルチテナント シナリオでは、認証エンドポイントを botframework.com テナントに設定します。

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHTYPE=certificate
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID={app-id-guid}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTPEMFILE={path-to-pem-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CERTKEYFILE={path-to-key-file}
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__AUTHORITY=https://login.microsoftonline.com/botframework.com

接続マネージャーの設定

MsalConnectionManager クラスはエージェントの複数の認証接続を管理できます。 接続構成を読み取り、名前付き接続ごとに MsalAuth インスタンスを作成します。

以下は、接続マネージャーを設定し、エージェントを起動する方法の例です。

from os import environ

from microsoft_agents.hosting.aiohttp import start_agent_process, CloudAdapter
from microsoft_agents.hosting.core import Authorization, AgentApplication, TurnState, MemoryStorage

from dotenv import load_dotenv
from aiohttp.web import Request, Response, Application, run_app
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.activity import load_configuration_from_env

def start_server(
    agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
):
    async def entry_point(req: Request) -> Response:
        agent: AgentApplication = req.app["agent_app"]
        adapter: CloudAdapter = req.app["adapter"]
        return await start_agent_process(req, agent, adapter)

    APP = Application()
    APP.router.add_post("/api/messages", entry_point)
    APP["agent_configuration"] = auth_configuration
    APP["agent_app"] = agent_application
    APP["adapter"] = agent_application.adapter

    try:
        run_app(APP, host="localhost", port=environ.get("PORT", 3978))
    except Exception as error:
        raise error

load_dotenv()
agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

start_server(
    agent_application=AGENT_APP, auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration()
)

Python エージェントで MsalConnectionManager を使用にする完全なコード例は、Python クイックスタート サンプル を参照してください。

カスタム認証プロバイダー

カスタマイズされた認証プロバイダーを必要とするユーザーは、AccessTokenProviderBase 基本クラスを実装できます。

from microsoft_agents.hosting.core import AccessTokenProviderBase

class CustomAuthProvider(AccessTokenProviderBase):
    async def get_access_token(
        self, resource_url: str, scopes: list[str], force_refresh: bool = False
    ) -> str:
        # Implement custom token acquisition logic
        token = await your_custom_token_logic(resource_url, scopes)
        return token

認証のログ記録のサポート

MSAL 認証システムは、ロガー名 microsoft_agents.authentication.msal で標準の Python logging モジュールを使用します。 トークン取得のトラブルシューティングのために認証フローの詳細なログ記録を有効にするには、アプリケーションでロガーを構成します。

import logging

logging.basicConfig(level=logging.WARNING)
logging.getLogger("microsoft_agents.authentication.msal").setLevel(logging.DEBUG)