Aufrufen von benutzerdefinierten APIs von einem Agent mithilfe von .NET

Es gibt mehrere Möglichkeiten, benutzerdefinierte APIs von einem Agent aufzurufen. Abhängig von Ihrem Szenario können Sie entweder IDownstreamApi, MicrosoftIdentityMessageHandler oder IAuthorizationHeaderProvider. In diesem Leitfaden werden die verschiedenen Ansätze zum Aufrufen ihrer eigenen geschützten APIs auf alle drei Arten erläutert.

Um eine API von einem Agent aufzurufen, müssen Sie ein Zugriffstoken abrufen, das der Agent verwenden kann, um sich selbst bei der API zu authentifizieren. Wir empfehlen die Verwendung des Microsoft.Identity.Web SDK für .NET zum Aufrufen Ihrer Web-APIs. Dieses SDK vereinfacht den Prozess des Abrufens und Validierens von Token. Verwenden Sie für andere Sprachen das Microsoft Entra-Agent-SDK für die Agent-ID.

Voraussetzungen

Eine Agentidentität mit entsprechenden Berechtigungen zum Aufrufen der Ziel-API. Sie benötigen einen Benutzer für den On-Behalf-of-Flow.
Ein Agentbenutzer mit entsprechenden Berechtigungen zum Aufrufen der Ziel-API.

Entscheiden, welcher Ansatz basierend auf Ihrem Szenario verwendet werden soll

In der folgenden Tabelle können Sie entscheiden, welcher Ansatz verwendet werden soll. Für die meisten Szenarien empfehlen wir die Verwendung IDownstreamApi.

Vorgehensweise	Kompliziertheit	Flexibilität	Anwendungsfall
`IDownstreamApi`	Low	Mittelstufe	Standard-REST-APIs mit Konfiguration
`MicrosoftIdentityMessageHandler`	Mittelstufe	High	HttpClient mit Direct Injection (DI) und composable Pipeline
`IAuthorizationHeaderProvider`	High	Sehr hoch	Vollständige Kontrolle über HTTP-Anforderungen

IDownstreamApi ist die bevorzugte Methode zum Aufrufen einer geschützten API zwischen den drei Optionen. Es ist sehr konfigurierbar und erfordert minimale Codeänderungen. Es bietet auch die automatische Token-Erfassung.

Verwenden Sie IDownstreamApi, wenn Sie die folgenden Elemente benötigen:

Sie rufen standardmäßige REST-APIs auf
Sie möchten einen konfigurationsgesteuerten Ansatz
Sie benötigen die automatische Serialisierung/Deserialisierung.
Sie möchten minimalen Code schreiben

MicrosoftIdentityMessageHandler aus dem Microsoft.Identity.Web.TokenAcquisition-Paket ist ein delegierender Handler, der Authentifizierung zu HttpClient-Anfragen hinzufügt. Verwenden Sie diese Funktion, wenn Sie vollständige HttpClient-Funktionen mit automatischer Tokenerfassung benötigen.

Auf das Microsoft.Identity.Web.TokenAcquisition-Paket wird bereits von Microsoft.Identity.Web.AgentIdentities verwiesen.

Verwenden Sie MicrosoftIdentityMessageHandler, wenn Sie die folgenden aufgelisteten Elemente benötigen.

Sie benötigen eine differenzierte Kontrolle über HTTP-Anforderungen
Sie möchten mehrere Nachrichtenhandler verfassen
Sie integrieren Code, der auf dem vorhandenen HttpClient basiert.
Sie benötigen Zugriff auf unformatierte HttpResponseMessage

IAuthorizationHeaderProvider über Microsoft.Identity.Web erhalten Sie direkten Zugriff auf Autorisierungsheader, um die vollständige Kontrolle über HTTP-Anforderungen zu erhalten. Dies bedeutet, dass Sie den Authentifizierungsprozess an Ihre Anforderungen anpassen können, einschließlich des Hinzufügens oder Änderns von Headern nach Bedarf. Mit dieser Methode können Sie auch benutzerdefinierte HTTP-Bibliotheken verwenden, um API-Aufrufe zu tätigen.

Verwenden Sie IAuthorizationHeaderProvider, wenn Sie die folgenden Elemente benötigen:

Sie benötigen vollständige Kontrolle über die HTTP-Anforderungserstellung.
Sie integrieren sich in nicht standardmäßige HTTP-APIs
Sie müssen HttpClient ohne DI verwenden
Sie erstellen benutzerdefinierte HTTP-Abstraktionen

Aufrufen Ihrer API

Nachdem Sie ermittelt haben, was für Sie funktioniert, rufen Sie ihre benutzerdefinierte Web-API auf.

Warnung

Geheime Clientschlüssel sollten aufgrund von Sicherheitsrisiken nicht als Clientanmeldeinformationen in Produktionsumgebungen für Agentidentitäts-Blueprints verwendet werden. Verwenden Sie stattdessen sicherere Authentifizierungsmethoden wie Verbundidentitätsanmeldeinformationen (FIC) mit verwalteten Identitäten oder Clientzertifikaten. Diese Methoden bieten eine verbesserte Sicherheit, da vertrauliche geheime Schlüssel nicht direkt in Ihrer Anwendungskonfiguration gespeichert werden müssen.

Installieren Sie das erforderliche NuGet-Paket:

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

Konfigurieren Sie tokenanmeldeinformationsoptionen und Ihre APIs in appsettings.json.

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

Konfigurieren Sie Ihre Dienste, um nachgeschaltete API-Unterstützung hinzuzufügen:

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

Rufen Sie Ihre geschützte API mithilfe von IDownstreamApi. Beim Aufrufen der API können Sie die Agent-Identität oder die Agent-Benutzeridentität mithilfe der WithAgentIdentity oder WithAgentUserIdentity Methoden angeben. IDownstreamApi verarbeitet automatisch die Tokenerfassung und fügt das Zugriffstoken an die Anforderung an.

Sie können für WithAgentIdentity die API entweder mit einem nur für App Token (autonomer Agent) oder im Auftrag eines Benutzers (interaktiver Agent) aufrufen.

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

Für WithAgentUserIdentitydiese Eigenschaft können Sie entweder den Benutzerprinzipalnamen (User Principal Name, UPN) oder die Objektidentität (Object Identity, OID) angeben, um den Agentbenutzer zu identifizieren.

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

}

Installieren Sie das erforderliche NuGet-Paket:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Konfigurieren Sie Ihre Dienste, so dass sie die Authentifizierung mit Agentidentitäten hinzufügen und HttpClient bei MicrosoftIdentityMessageHandler registrieren:

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

Erwerben Sie token, und rufen Sie Ihre geschützte API mit dem konfigurierten HttpClient auf. Sie können die Agentenidentität oder den Agentbenutzer mithilfe der WithAgentIdentity oder WithAgentUserIdentity Methoden angeben.

Für WithAgentIdentity rufen Sie die API entweder mit einem nur-App-Token (autonomer Agent) oder im Namen eines Benutzers (interaktiver Agent) auf.

Um die API mit einem Nur-App-Token für die Agentidentität aufzurufen, setzen Sie RequestAppToken auf 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();
    }
}

Um die API im Auftrag eines Benutzers für die Identität des Agenten aufzurufen, setzen Sie RequestAppToken nicht oder legen Sie sie explizit auf false fest.

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

Zur Verwendung WithAgentUserIdentitykönnen Sie entweder UPN oder OID angeben, um den Agentbenutzer zu identifizieren.

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

Installieren Sie das erforderliche NuGet-Paket:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Konfigurieren Sie Ihre Dienste, um die Authentifizierung mit Agentidentitäten hinzuzufügen:

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

Konfigurieren von Authentifizierungsanmeldeinformationen in appsettings.json

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

Rufen Sie dann die Web-API auf, und extrahieren Sie das Zugriffstoken.

Rufen WithAgentIdentitySie die API entweder mit einem Nur-App-Token (autonomem Agent) oder im Auftrag eines Benutzers (interaktiver Agent) auf.

Verwenden Sie für das "Nur-App-Token"-Szenario die Methode CreateAuthorizationHeaderForAppAsync.
Verwenden Sie die Methode CreateAuthorizationHeaderForUserAsync für das OBO-Tokenszenario.

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

Für WithAgentUserIdentity, rufen Sie die API im Namen eines Benutzers mit ihrem UPN oder OID auf.

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

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-19

Freigeben über

Aufrufen von benutzerdefinierten APIs von einem Agent mithilfe von .NET

Voraussetzungen

Entscheiden, welcher Ansatz basierend auf Ihrem Szenario verwendet werden soll

Aufrufen Ihrer API

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen