.NET エージェントで認証を構成する

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

このユーティリティは、アクセス トークンの作成に使用できる複数の異なるプロファイルをサポートしています。 各アクセス トークンは、以下の認証タイプいずれかを使用して作成できま:

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

接続を構成する

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

次のセクションでは、MSAL 認証プロバイダーでサポートされている認証の種類ごとに必要な構成設定とオプションの構成設定と、各種類の構成スニペットの例について説明します。

ClientSecret を使用したシングルテナント

シングルテナント* 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"
          ],
      }
    }
  }

ClientSecret を使用した MultiTenant

マルチテナント ClientSecretの 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"
          ],
      }
    }
  }

UserManagedIdentity

UserManagedIdentity の appsettings の例を次に示します:

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

SystemManagedIdentity

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

SystemManagedIdentity 認証の種類の appsettings の例を次に示します:

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

FederatedCredentials

FederatedCredentials の 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"
        ]
      }
    }
  }

WorkloadIdentity

シングルテナント 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 クライアント アサーション オプション

  "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,
        }
      }
    }
  }

CertificateSubjectName

サブジェクト名と発行者 (SNI) とマルチテナントの CertificateSubjectName のアプリ設定の例を次に示します。

  "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 および CertificateSubjectName 向けの 用 appsettings の例は以下の通りです

  "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"
        ]
      }
    }
  },

Certificate

証明書のサムプリントを使用した CertificateSubjectName の 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 の既定設定をエージェントに追加するサービス プロバイダー拡張機能を提供します。

ASP.NET Core ホスト用の既定の MSAL 構成プロバイダーの例を次に示します:

Program.cs クラス内。

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

// 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 認証プロバイダーを使用して作成されるすべてのクライアントと共有されます。 これらの設定は、IConfiguration Reader から読み込まれることを意図しており、設定セクション内の「MSALConfiguration」というセクションから読み込まれます。

appsettings.json ファイル内のエントリの例を次に示します:

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

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

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

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

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

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

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

MSAL 認証システムでは、トークン取得のトラブルシューティングを行う必要がある場合に、テレメトリ統合用の認証フローの独立したログ記録が可能になります。

ログ記録を有効にするには、アプリケーションの設定に Microsoft.Agents.Authentication.Msal のエントリを追加し、接続のトークン操作を報告する ILogger を設定します。MSALEnabledLogPII オプションを追加している場合、これには接続の個人識別情報 (PII) も含まれます。

この場合のログ ブロックの例を次に示します:

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

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