.NET を使用してエージェントからカスタム API を呼び出す

エージェントからカスタム API を呼び出すには、複数の方法があります。シナリオに応じて、 IDownstreamApi、 MicrosoftIdentityMessageHandler、または IAuthorizationHeaderProviderのいずれかを使用できます。このガイドでは、独自の保護された API を呼び出すためのさまざまな方法について、3 つの方法すべてについて説明します。

エージェントから API を呼び出すには、エージェントが API に対して自身を認証するために使用できるアクセストークンを取得する必要があります。 Microsoft.Identity.Web SDK for .NET を使用して Web API を呼び出することをお勧めします。この SDK は、トークンの取得と検証のプロセスを簡略化します。他の言語の場合は、エージェント ID に Microsoft Entra エージェント SDK を使用します。

[前提条件]

ターゲット API を呼び出す適切なアクセス許可を持つエージェント ID。代理操作のフローにはユーザーが必要です。
ターゲット API を呼び出す適切なアクセス許可を持つエージェントユーザー。

シナリオに基づいて使用する方法を決定する

次の表は、使用する方法を決定するのに役立ちます。ほとんどのシナリオでは、 IDownstreamApiを使用することをお勧めします。

方法	複雑さ	柔軟性	使用事例
`IDownstreamApi`	Low	ミディアム	構成による標準 REST API
`MicrosoftIdentityMessageHandler`	ミディアム	High	直接挿入 (DI) と構成可能なパイプラインを使用した HttpClient
`IAuthorizationHeaderProvider`	High	非常に高	HTTP 要求を完全に制御する

IDownstreamApi は、3 つのオプションの中から保護された API を呼び出す推奨される方法です。これは高度に構成可能であり、最小限のコード変更が必要です。また、トークンの自動取得も提供します。

次の項目が必要な場合は、 IDownstreamApi を使用します。

標準 REST API を呼び出している
構成主導型のアプローチが必要です
自動シリアル化/逆シリアル化が必要です
最小限のコードを記述する

MicrosoftIdentityMessageHandler Microsoft.Identity.Web.TokenAcquisition パッケージは、HttpClient 要求に認証を追加する委任ハンドラーです。これは、トークンの自動取得で完全な HttpClient 機能が必要な場合に使用します。

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

次の項目が必要な場合は、 MicrosoftIdentityMessageHandler を使用します。

HTTP 要求をきめ細かく制御する必要がある
複数のメッセージハンドラーを作成する場合
既存の HttpClient ベースのコードと統合している
生の HttpResponseMessage にアクセスする必要がある

IAuthorizationHeaderProvider microsoft.Identity.Web から承認ヘッダーに直接アクセスして、HTTP 要求を完全に制御できます。つまり、必要に応じてヘッダーを追加または変更するなど、ニーズに合わせて認証プロセスをカスタマイズできます。このメソッドでは、カスタム HTTP ライブラリを使用して API 呼び出しを行うこともできます。

次の項目が必要な場合は、 IAuthorizationHeaderProvider を使用します。

HTTP 要求の構築を完全に制御する必要がある
非標準の HTTP API と統合している
DI なしで HttpClient を使用する必要がある
カスタム HTTP 抽象化を構築している

API を呼び出す

何が適切かを判断したら、カスタム Web API の呼び出しに進みます。

Warnung

セキュリティリスクのために、エージェント ID ブループリントの運用環境では、クライアントシークレットをクライアント資格情報として使用しないでください。代わりに、マネージド ID またはクライアント証明書を使用するフェデレーション ID 資格情報 (FIC) などのより安全な認証方法を使用してください。これらの方法により、アプリケーション構成内に機密性の高いシークレットを直接格納する必要がなくなり、セキュリティが強化されます。

必要な NuGet パッケージをインストールします。

dotnet add package Microsoft.Identity.Web.DownstreamApi
dotnet add package Microsoft.Identity.Web.AgentIdentities

appsettings.jsonでトークン資格情報オプションと API を構成します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-blueprint-id",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  },
  "DownstreamApis": {
    "MyApi": {
      "BaseUrl": "https://api.example.com",
      "Scopes": ["api://my-api-client-id/read", "api://my-api-client-id/write"],
      "RelativePath": "/api/v1",
      "RequestAppToken": false
    }
  }
}

ダウンストリーム API サポートを追加するようにサービスを構成します。

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Register downstream APIs
builder.Services.AddDownstreamApis(
    builder.Configuration.GetSection("DownstreamApis"));

// Add Agent Identities support
builder.Services.AddAgentIdentities();

builder.Services.AddControllersWithViews();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

IDownstreamApiを使用して保護された API を呼び出します。 API を呼び出すときは、 WithAgentIdentity または WithAgentUserIdentity メソッドを使用して、エージェント ID またはエージェントユーザー ID を指定できます。 IDownstreamApi は、トークンの取得を自動的に処理し、アクセストークンを要求にアタッチします。

WithAgentIdentityの場合は、アプリ専用トークン (自律エージェント) を使用して API を呼び出すか、ユーザーの代わりに (対話型エージェント) API を呼び出します。

using Microsoft.Identity.Abstractions;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize]
public class ProductsController : Controller
{
    private readonly IDownstreamApi _api;

    public ProductsController(IDownstreamApi api)
    {
        _api = api;
    }

    // GET request for app only token scenario for agent identity
    public async Task<IActionResult> Index()
    {

        string agentIdentity = "<your-agent-identity>";
        var products = await _api.GetForAppAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentIdentity(agentIdentity));

        return View(products);
    }

    // GET request for on-behalf of user token scenario for agent identity
    public async Task<IActionResult> UserProducts()
    {

        string agentIdentity = "<your-agent-identity>";
        var products = await _api.GetForUserAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentIdentity(agentIdentity));

        return View(products);
    }
}

WithAgentUserIdentityでは、エージェントユーザーを識別するために、ユーザープリンシパル名 (UPN) またはオブジェクト ID (OID) を指定できます。

using Microsoft.Identity.Abstractions;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize]
public class ProductsController : Controller
{
    private readonly IDownstreamApi _api;

    public ProductsController(IDownstreamApi api)
    {
        _api = api;
    }

    // GET request for agent user identity using UPN
    public async Task<IActionResult> Index()
    {

        string agentIdentity = "<your-agent-identity>";
        string userUpn = "user@contoso.com";

        var products = await _api.GetForUserAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentUserIdentity(agentIdentity, userUpn));
        return View(products);
    }

    // GET request for agent user identity using OID
    public async Task<IActionResult> UserProducts()
    {

        string agentIdentity = "<your-agent-identity>";
        string userOid = "user-object-id";

        var products = await _api.GetForUserAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentUserIdentity(agentIdentity, userOid));

        return View(products);
    }

}

必要な NuGet パッケージをインストールします。
```
dotnet add package Microsoft.Identity.Web.AgentIdentities
```

エージェント ID を使用して認証を追加し、httpClient を MicrosoftIdentityMessageHandler に登録するようにサービスを構成します。

using Microsoft.Identity.Web;
using Microsoft.Identity.Abstractions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Configure named HttpClient with authentication
builder.Services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
    client.DefaultRequestHeaders.Add("Accept", "application/json");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddHttpMessageHandler(sp =>
{
    var authProvider = sp.GetRequiredService<IAuthorizationHeaderProvider>();
    return new MicrosoftIdentityMessageHandler(
        authProvider,
        new MicrosoftIdentityMessageHandlerOptions
        {
            Scopes = new[] { "api://my-api-client-id/read" },
        });
});

builder.Services.AddControllersWithViews();

// Add Agent Identities support
builder.Services.AddAgentIdentities();


var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

構成された HttpClient を使用してトークンを取得し、保護された API を呼び出します。 WithAgentIdentityまたはWithAgentUserIdentityメソッドを使用して、エージェント ID またはエージェントユーザーを指定できます。

エージェント ID のアプリ専用トークンを使用して API を呼び出すには、 RequestAppToken を true に設定します。

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
        string agentIdentity = "<your-agent-identity>";
        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();
    }
}

エージェント ID に対してユーザーの代わりに API を呼び出すには、 RequestAppToken を設定したり、明示的に false に設定したりしないでください。

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
        string agentIdentity = "<your-agent-identity>";
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = false;
            });

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

WithAgentUserIdentityを使用するには、エージェントユーザーを識別するために UPN または OID を指定します。

// Create request with agent user identity authentication with UPN
public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    string agentIdentity = "<your-agent-identity>";
    string userUpn = "<your-user-upn>";

    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();
}

// Create request with agent user identity authentication with OID
public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    string agentIdentity = "<your-agent-identity>";
    string userOid = "<your-user-oid>";

    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options => 
        {
            options.WithAgentUserIdentity(agentIdentity, userOid);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

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

必要な NuGet パッケージをインストールします。
```
dotnet add package Microsoft.Identity.Web.AgentIdentities
```

エージェント ID を使用して認証を追加するようにサービスを構成します。

using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// With Microsoft.Identity.Web
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();

builder.Services.AddAgentIdentities();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

appsettings.json で認証資格情報を構成する

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-blueprint-id",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

アクセストークンを取得して抽出し、Web API を呼び出します。

アプリのみのトークンシナリオでは、 CreateAuthorizationHeaderForAppAsync メソッドを使用します。
OBO トークンのシナリオでは、 CreateAuthorizationHeaderForUserAsync メソッドを使用します

using Microsoft.Identity.Abstractions;

[Authorize]
public class CustomApiController : Controller
{
    private readonly IAuthorizationHeaderProvider _headerProvider;

    public CustomApiController(
        IAuthorizationHeaderProvider headerProvider,
    {
        _headerProvider = headerProvider;
    }

    // App only token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // 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
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForAppAsync(
            scopes: new[] { "api://my-api/.default" }, options: options);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }

    // On-behalf of user token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // 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
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForUserAsync(
            scopes: new[] { "api://my-api/.default" }, options: options);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }
}

WithAgentUserIdentityの場合は、UPN または OID を使用してユーザーに代わって API を呼び出します。

using Microsoft.Identity.Abstractions;

[Authorize]
public class CustomApiController : Controller
{
    private readonly IAuthorizationHeaderProvider _headerProvider;

    public CustomApiController(IAuthorizationHeaderProvider headerProvider)
    {
        _headerProvider = headerProvider;
    }

    // App only token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // Configure options for the agent identity
        string agentIdentity = "agent-identity-guid";
        string userUpn = "user@contoso.com";

        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentUserIdentity(agentIdentity, userUpn);

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

        // Acquire an access token for the agent identity
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForAppAsync(
            scopes: new[] { "api://my-api/.default" }, options: options, user: user);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }

    // On-behalf of user token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // Configure options for the agent identity
        string agentIdentity = "agent-identity-guid";
        string userUpn = "user@contoso.com";

        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentUserIdentity(agentIdentity, userUpn);

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

        // Acquire an access token for the agent identity
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForAppAsync(
            scopes: new[] { "api://my-api/.default" }, options: options, user: user);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }
}

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-19

次の方法で共有

.NET を使用してエージェントからカスタム API を呼び出す

[前提条件]

シナリオに基づいて使用する方法を決定する

API を呼び出す

関連コンテンツ

フィードバック

その他のリソース