Microsoft.Identity.Web を使用してエージェント ID を認証します。

.NETではないのですか? Entra SDK コンテナーのドキュメントについては、Entra SDK コンテナーのサイドカーを参照してください。 コンテナー サイドカーは、任意の言語とプラットフォームでエージェント ID をサポートします。

エージェントのアイデンティティを理解する

Microsoft。Identity.Web.AgentIdentities NuGet パッケージは、Microsoft Entra IDでのエージェント ID のサポートを提供します。 これにより、アプリケーションは、エージェント アプリケーション、エージェント ID、およびエージェント ユーザー ID のトークンを安全に認証して取得できます。これは、自律エージェント、ユーザーに代わって動作する対話型エージェント、および独自のユーザー ID を持つエージェントに役立ちます。

このパッケージは、Microsoft.Identity.Web ライブラリスイートの一部であり、バージョン 3.10.0 で追加されました。

主要な概念を確認する

エージェント ID の操作には、次の概念が不可欠です。

エージェント ID ブループリントを定義する

エージェント ID ブループリントには、エージェント ID またはエージェント ユーザー ID に代わって動作するためのアクセス許可を持つ特別なアプリケーション登録が Microsoft Entra にあります。 アプリケーション ID (エージェント ID ブループリント クライアント ID) で表されます。 エージェント ID ブループリントは、資格情報 (通常は FIC+MSI またはクライアント証明書) と、グラフを呼び出すためにそれ自体のトークンを取得するためのアクセス許可を使用して構成されます。 これは、開発するアプリです。 これは機密クライアント アプリケーションであり、通常は Web API です。 管理できる唯一のアクセス許可は、(Microsoft Graphを使用して) エージェント ID を作成/削除することです。

エージェント ID を作成する

エージェント アイデンティティは、Microsoft Entra の特別なサービス プリンシパルです。 これは、エージェント ID ブループリントによって作成され、偽装が承認されている ID を表します。 独自の資格情報はありません。 エージェント ID ブループリントは、ユーザーまたはテナント管理者がエージェント ID に対して対応するスコープに同意していれば、エージェント ID に代わってトークンを取得できます。 自律エージェントは、エージェント ID に代わってアプリ トークンを取得します。 ユーザー トークンを使用して呼び出された対話型エージェントは、エージェント ID に代わってユーザー トークンを取得します。

エージェント ユーザー ID を作成する

エージェント ユーザー ID は、ユーザーとしても機能するエージェント ID です (独自のメールボックスを持つエージェント ID、またはディレクトリ内のユーザーに報告するエージェント ID と考えてください)。 エージェント アプリケーションは、エージェント ユーザー ID に代わってトークンを取得できます。

フェデレーションアイデンティティの資格情報を理解する (FIC)

FIC は、アプリケーションが OpenID Connect (OIDC) トークンを使用して相互に信頼できるようにする、Microsoft Entraの信頼メカニズムです。 エージェント ID のコンテキストでは、FIC を使用して、エージェント アプリケーション ID とエージェント ID、およびエージェント ID とエージェント ユーザー ID の間の信頼を確立します。

詳細情報の検索

Microsoft Entra エージェント ID の詳細については、Microsoft Entra エージェント ID ドキュメントを参照してください。

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

次のコマンドを実行して、NuGet パッケージをプロジェクトに追加します。

dotnet add package Microsoft.Identity.Web.AgentIdentities

エージェント ID を実装する

アプリケーションでエージェント ID を構成して使用するには、次の手順に従います。

1. サービスを構成する

まず、必要なサービスをアプリケーションに登録します。

// Add the core Identity Web services
services.AddTokenAcquisition();
services.AddInMemoryTokenCaches();
services.AddHttpClient();

// Add Microsoft Graph integration if needed.
// Requires the Microsoft.Identity.Web.GraphServiceClient package
services.AddMicrosoftGraph();

// Add Agent Identities support
services.AddAgentIdentities();

2.エージェント ID ブループリントを構成する

appsettings.jsonを使用して、必要な資格情報を使用してエージェント ID ブループリント アプリケーションを構成します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-client-id",

    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertificateName"
      }

      // Or for Federation Identity Credential with Managed Identity:
      // {
      //   "SourceType": "SignedAssertionFromManagedIdentity",
      //   "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      // }
    ]
  }
}

または、必要に応じて、プログラムで構成します。

// Configure the information about the agent application
services.Configure<MicrosoftIdentityApplicationOptions>(
    options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "agent-application-client-id";
        options.ClientCredentials = [
            CertificateDescription.FromStoreWithDistinguishedName(
                "CN=YourCertificateName", StoreLocation.LocalMachine, StoreName.My)
        ];
    });

資格情報を表すすべての方法については、 https://aka.ms/ms-id-web/credential-description を参照してください。

ASP.NET Coreで、サービスのオーバーライドを使用します。認証スキームの取得を構成します。 OWIN 上で ASP.NET Core アプリケーションを使用している場合は（新しいアプリには推奨されません）、Microsoft.Identity.Web.Owin を使用することもできますし、デーモン アプリケーションを作成することも可能です。

3. エージェント ID を使用する

エージェントのシナリオに基づいて、適切なトークン取得パターンを選択します。

エージェント ID のトークンを取得する

これらのパターンを使用して、自律的または対話型のシナリオでエージェント ID のトークンを取得します。

自律エージェントのアプリ トークンを取得する

自律エージェント アプリケーションがエージェント ID の アプリ専用 トークンを取得するには:

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync("https://resource/.default", options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)
対話型エージェントのユーザー トークンを取得する

対話型エージェント アプリケーションが、Web API を呼び出す ユーザー に代わってエージェント ID のユーザー トークンを取得するには、次のようにします。

// Get the required services from the DI container
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent identity
string agentIdentity = "agent-identity-guid";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentIdentity(agentIdentity);

// Acquire an access token for the agent identity
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForAppAsync(["https://resource/.default"], options);

// The authHeader contains "Bearer " + the access token (or another protocol
// depending on the options)

エージェント ユーザー ID のトークンを取得する

エージェント アプリケーションがエージェント ユーザー ID に代わってトークンを取得するには、ユーザーの UPN (ユーザー プリンシパル名) または OID (オブジェクト ID) を使用できます。

UPN による認証 (ユーザー プリンシパル名)

次の例では、ユーザーの UPN を指定してユーザー トークンを取得します。

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using UPN
string agentIdentity = "agent-identity-client-id";
string userUpn = "user@contoso.com";
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userUpn);

// Create a ClaimsPrincipal to enable token caching
ClaimsPrincipal user = new ClaimsPrincipal();

// Acquire a user token
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForUserAsync(
        scopes: ["https://graph.microsoft.com/.default"],
        options: options,
        user: user);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.
OID を使用した認証 (オブジェクト ID)

次の例では、ユーザーの OID を指定してユーザー トークンを取得します。

// Get the required services
IAuthorizationHeaderProvider authorizationHeaderProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Configure options for the agent user identity using OID
string agentIdentity = "agent-identity-client-id";
Guid userOid = Guid.Parse("e1f76997-1b35-4aa8-8a58-a5d8f1ac4636");
var options = new AuthorizationHeaderProviderOptions()
    .WithAgentUserIdentity(agentIdentity, userOid);

// Create a ClaimsPrincipal to enable token caching
ClaimsPrincipal user = new ClaimsPrincipal();

// Acquire a user token
string authHeader = await authorizationHeaderProvider
    .CreateAuthorizationHeaderForUserAsync(
        scopes: ["https://graph.microsoft.com/.default"],
        options: options,
        user: user);

// The user object now has claims including uid and utid. If you use it
// in another call it will use the cached token.

4. Microsoft Graphとの統合

Microsoft.Identity.Web.AgentIdentities パッケージをインストールすると、エージェント ID のサポートが追加されます。

dotnet add package Microsoft.Identity.Web.AgentIdentities

サービス コレクションにMicrosoft Graphのサポートを追加します。

services.AddMicrosoftGraph();

これで、サービス プロバイダーから GraphServiceClient を取得できるようになりました。

エージェント ID を使用してMicrosoft Graphを呼び出す

次の例では、エージェント ID を使用Microsoft Graph API を呼び出します。

// Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

// Call Microsoft Graph APIs with the agent identity
var applications = await graphServiceClient.Applications
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true;
    }));

エージェント ユーザー ID を使用してMicrosoft Graphを呼び出す

MICROSOFT GRAPHで UPN または OID を使用できます。

// Get the GraphServiceClient
GraphServiceClient graphServiceClient = serviceProvider.GetRequiredService<GraphServiceClient>();

// Call Microsoft Graph APIs with the agent user identity using UPN
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userUpn)));

// Or using OID
var me = await graphServiceClient.Me
    .GetAsync(r => r.Options.WithAuthenticationOptions(options =>
        options.WithAgentUserIdentity(agentIdentity, userOid)));

5. ダウンストリーム API との統合

IDownstreamApi抽象化を使用して他の API を呼び出すには:

  1. Microsoft.Identity.Web.DownstreamApi パッケージをインストールします。このパッケージは IDownstreamApi の抽象化を提供します。
dotnet add package Microsoft.Identity.Web.DownstreamApi
  1. ダウンストリーム API のパラメーターを指定して、構成に DownstreamApis セクションを追加します。
"AzureAd":{
    // usual config
},
"DownstreamApis":{
   "MyApi":
   {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [ "https://myapi.domain.com/read", "https://myapi.domain.com/write" ]
   }
}
  1. サービス コレクションにダウンストリーム API のサポートを追加します。
services.AddDownstreamApis(Configuration.GetSection("DownstreamApis"));

サービス プロバイダーから IDownstreamApi サービスにアクセスし、任意の HTTP 動詞を使用して "MyApi" API を呼び出すようになりました。 次の例では、エージェント ID とエージェント ユーザー ID を使用して API を呼び出す方法を示します。

// Get the IDownstreamApi service
IDownstreamApi downstreamApi = serviceProvider.GetRequiredService<IDownstreamApi>();

// Call API with agent identity
var response = await downstreamApi.GetForAppAsync<string>(
    "MyApi",
    options => options.WithAgentIdentity(agentIdentity));

// Call API with agent user identity using UPN
var userResponse = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userUpn));

// Or using OID
var userResponseByOid = await downstreamApi.GetForUserAsync<string>(
    "MyApi",
    options => options.WithAgentUserIdentity(agentIdentity, userOid));

6. Azure SDKとの統合

Azure SDKを呼び出すには、Microsoft.Identity.Web.Azure NuGet パッケージのMicrosoftIdentityAzureCredentialクラスを使用します。

Microsoft.Identity.Web.Azure パッケージをインストールします。

dotnet add package Microsoft.Identity.Web.Azure

Azure トークン資格情報のサポートをサービス コレクションに追加します。

services.AddMicrosoftIdentityAzureTokenCredential();

これで、サービス プロバイダーから MicrosoftIdentityTokenCredential を取得できるようになりました。 このクラスには、 .WithAgentIdentity() または .WithAgentUserIdentity() メソッドを適用できるメンバー Options があります。

詳細については、Azure SDK統合を参照してください。

7. MicrosoftIdentityMessageHandler を使用して HttpClient を構成する

柔軟な認証オプションで HttpClient を直接使用するには、Microsoft.Identity.Web.TokenAcquisition パッケージの MicrosoftIdentityMessageHandler を使用します。

注: Microsoft.Identity.Web.TokenAcquisition パッケージは、Microsoft.Identity.Web.AgentIdentities によって既に参照されています。

MicrosoftIdentityMessageHandler を使用してエージェント ID を認証する

次の例では、エージェント ID 認証を使用して HttpClient を構成します。

// Configure HttpClient with MicrosoftIdentityMessageHandler in DI
services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://myapi.domain.com");
})
.AddMicrosoftIdentityMessageHandler(options =>
{
    options.Scopes= { "https://myapi.domain.com/.default" }
});

// Usage in your service or controller
public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("MyApiClient");
    }

    public async Task<string> CallApiWithAgentIdentity(string agentIdentity)
    {
        // Create request with agent identity authentication
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = true;
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

MicrosoftIdentityMessageHandler を使用してエージェント ユーザー ID を認証する

次の例では、エージェント ユーザー ID で認証された要求を送信します。

public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    // Create request with agent user identity authentication
    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options =>
        {
            options.WithAgentUserIdentity(agentIdentity, userUpn);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

HttpClient を手動で構成する

さらに制御できるようにハンドラーを手動で構成することもできます。

// Get the authorization header provider
IAuthorizationHeaderProvider headerProvider =
    serviceProvider.GetRequiredService<IAuthorizationHeaderProvider>();

// Create the handler with default options
var handler = new MicrosoftIdentityMessageHandler(
    headerProvider,
    new MicrosoftIdentityMessageHandlerOptions
    {
        Scopes = { "https://graph.microsoft.com/.default" }
    });

// Create HttpClient with the handler
using var httpClient = new HttpClient(handler);

// Make requests with per-request authentication options
var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.microsoft.com/v1.0/applications")
    .WithAuthenticationOptions(options =>
    {
        options.WithAgentIdentity(agentIdentity);
        options.RequestAppToken = true;
    });

var response = await httpClient.SendAsync(request);

MicrosoftIdentityMessageHandler は、エージェント ID の既存の Microsoft Identity Web 拡張メソッドとの完全な互換性を維持しながら、HttpClient ベースのコードに認証を追加する柔軟で構成可能な方法を提供します。

エージェント ID からトークンを検証する

エージェント ID またはエージェント ユーザー ID に対して取得されたトークンを、任意の Web API の場合と同じ方法で検証します。 ただし、次のことも可能です。

  • エージェント ID とエージェント ブループリントに対してトークンが発行されたかどうかを確認します。

    HttpContext.User.GetParentAgentBlueprint()

    は、トークンがエージェント ID (またはエージェント ユーザー ID) に対して発行された場合、親エージェント ブループリントの ClientId を返します。

  • エージェント ユーザー ID に対してトークンが発行されたかどうかを確認します。

    HttpContext.User.IsAgentUserIdentity()

これらの 2 つの拡張メソッドは、ClaimsIdentity と ClaimsPrincipal の両方に適用されます。

前提条件の確認

エージェント ID を実装する前に、これらの構成手順を完了してください。

Microsoft Entra登録の構成

  1. エージェント アプリケーションの構成:

    • Graph SDK にエージェント アプリケーションを登録する
    • エージェント アプリケーションのクライアント資格情報を追加する
    • エージェント ID を作成するための適切な API アクセス許可 (Application.ReadWrite.All など) を付与する
    • JSON の構成例: 
      {
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "agent-application-id",
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "LocalMachine/My",
        "CertificateDistinguishedName": "CN=YourCertName"
      }
    ]
  }
}

  2. エージェント ID の構成:

    • エージェントにエージェント ID を作成してもらう
    • エージェント ID が実行する必要がある内容に基づいて適切な API アクセス許可を付与する

  3. ユーザーのアクセス許可:

    • エージェント ユーザー ID のシナリオでは、適切なユーザーアクセス許可が構成されていることを確認します。

認証フローを理解する

内部では、Microsoft.Identity.Web.AgentIdentities パッケージ:

  1. フェデレーション ID 資格情報 (FIC) を使用して、エージェント アプリケーションとエージェント ID の間、およびエージェント ID とエージェント ユーザー ID の間の信頼を確立します。
  2. GetFicTokenAsync メソッドを使用して FIC トークンを取得します。
  3. FIC トークンを使用してエージェント ID として認証する
  4. エージェント ユーザー ID の場合、MSAL 拡張機能を利用してユーザー トークンの取得を実行します

一般的な問題のトラブルシューティング

エージェント ID を使用する場合の一般的な問題と解決策を確認します。

既知の問題を解決する

  1. Missing FIC 構成: エージェント アプリケーションとエージェント ID の間で Microsoft Entra を使用して、フェデレーション ID 資格情報が適切に構成されていることを確認します。

  2. アクセス許可の問題: エージェント アプリケーションにエージェント ID を管理するための十分なアクセス許可があること、およびエージェント ID にダウンストリーム API を呼び出すのに十分なアクセス許可があることを確認します。

  3. 証明書の問題: クライアント証明書を使用する場合は、証明書がアプリの登録に登録されていること、正しくインストールされていること、およびエージェント アプリケーション コードからアクセス可能であることを確認します。

  4. トークン取得エラー: ログ記録を有効にして、トークン取得エラーを診断します。 次のコードは、デバッグ レベルのコンソール ログを構成します。

    services.AddLogging(builder => {
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

その他のリソースを確認する

  • Last updated on