Vyvolání vlastních rozhraní API z agenta pomocí .NET

Existují různé způsoby volání vlastních rozhraní API z agenta. V závislosti na vašem scénáři můžete použít buď IDownstreamApi, MicrosoftIdentityMessageHandlernebo IAuthorizationHeaderProvider. Tato příručka vysvětluje různé přístupy pro volání vlastních chráněných rozhraní API všemi třemi způsoby.

Pokud chcete volat rozhraní API z agenta, musíte získat přístupový token, který může agent použít k ověření v rozhraní API. Doporučujeme použít Microsoft. Identity.Web SDK pro .NET pro volání webových rozhraní API Tato sada SDK zjednodušuje proces získávání a ověřování tokenů. Pro ostatní jazyky použijte sadu SDK Microsoft Entra ID Auth (sidecar).

Předpoklady

• Identita agenta s příslušnými oprávněními pro volání cílového rozhraní API. Pro tok v zastoupení potřebujete uživatele.
• Uživatelský účet agenta s příslušnými oprávněními pro volání cílového rozhraní API.

Rozhodněte se, který přístup se má použít v závislosti na vašem scénáři.

Následující tabulka vám pomůže rozhodnout, který přístup se má použít. Pro většinu scénářů doporučujeme použít IDownstreamApi.

Přístup	Složitost	Flexibilita	Případ použití
IDownstreamApi	Nízká úroveň	Středně	Standardní rozhraní REST API s konfigurací
MicrosoftIdentityMessageHandler	Středně	Vysoko	HttpClient s přímou injekcí (DI) a složitelným kanálem
IAuthorizationHeaderProvider	Vysoko	Velmi vysoká	Úplná kontrola nad požadavky HTTP

Použití IDownstreamApi

IDownstreamApi je upřednostňovaným způsobem volání chráněného rozhraní API mezi třemi možnostmi. Je vysoce konfigurovatelná a vyžaduje minimální změny kódu. Nabízí také automatické získávání tokenů.

Použijte IDownstreamApi , když potřebujete následující uvedené položky:

• Voláte standardní rozhraní REST API.
• Chcete přístup řízený konfigurací.
• Potřebujete automatickou serializaci/deserializaci.
• Chcete napsat minimální kód.

Použijte MicrosoftIdentityMessageHandler

MicrosoftIdentityMessageHandler z balíčku Microsoft.Identity.Web.TokenAcquisition je delegující handler, který přidává ověřování pro požadavky HttpClient. Tuto možnost použijte, pokud potřebujete úplné funkce HttpClient s automatickým získáním tokenů.

Balíček Microsoft.Identity.Web.TokenAcquisition je již referencován Microsoft.Identity.Web.AgentIdentities.

Použijte MicrosoftIdentityMessageHandler , když potřebujete následující uvedené položky:

• Potřebujete detailní kontrolu nad požadavky HTTP.
• Chcete vytvořit více zpracovatelů zpráv.
• Integrujete se s existujícím kódem založeným na HttpClient.
• Potřebujete přístup k nezpracované zprávě HttpResponseMessage.

Použijte IAuthorizationHeaderProvider

IAuthorizationHeaderProvider z Microsoft.Identity.Web poskytuje přímý přístup k autorizačním hlavičkám pro úplnou kontrolu nad HTTP požadavky. To znamená, že proces ověřování můžete přizpůsobit tak, aby vyhovoval vašim potřebám, včetně přidávání nebo úprav hlaviček podle potřeby. Tato metoda také umožňuje používat vlastní knihovny HTTP k volání rozhraní API.

Použijte IAuthorizationHeaderProvider , když potřebujete následující uvedené položky:

• Potřebujete úplnou kontrolu nad vytvářením požadavků HTTP.
• Integrujete se s nestandardními rozhraními API HTTP.
• Musíte použít HttpClient bez DI.
• Vytváříte vlastní abstrakce HTTP.

Zavolejte své rozhraní API

Po určení toho, co vám vyhovuje, pokračujte voláním vlastního webového rozhraní API.

Výstraha

Tajné kódy klienta by se neměly používat jako přihlašovací údaje klienta v produkčních prostředích pro podrobné plány identit agentů kvůli rizikům zabezpečení. Místo toho používejte bezpečnější metody ověřování, jako jsou přihlašovací údaje federované identity (FIC) se spravovanými identitami nebo klientskými certifikáty . Tyto metody poskytují lepší zabezpečení tím, že eliminují potřebu ukládat citlivé tajné kódy přímo v konfiguraci vaší aplikace.

Použití IDownstreamApi

1. Nainstalujte požadovaný balíček NuGet:

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

2. Konfigurace možností přihlašovacích údajů tokenu a vašich rozhraní API v 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
       }
     }
   }
   

3. Nakonfigurujte služby pro přidání podpory podřízených rozhraní API:

   using Microsoft.AspNetCore.Authentication.OpenIdConnect;
   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();
   

4. Zavolejte své chráněné rozhraní API pomocí IDownstreamApi. Při volání rozhraní API můžete určit identitu agenta nebo identitu uživatelského účtu agenta pomocí WithAgentIdentity metod nebo WithAgentUserIdentity metod. IDownstreamApi automaticky zpracuje získání tokenu a připojí přístupový token k požadavku.

   • V případě WithAgentIdentity buď zavoláte rozhraní API pomocí tokenu pouze pro aplikaci (autonomního agenta), nebo jménem uživatele (interaktivního agenta).

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

   • Pro WithAgentUserIdentityurčení uživatelského účtu agenta můžete zadat hlavní název uživatele (UPN) nebo identitu objektu (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's user account 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's user account 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);
         }
     
     }
     

Použijte MicrosoftIdentityMessageHandler

1. Nainstalujte požadovaný balíček NuGet:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Nakonfigurujte služby pro přidání ověřování s identitami agenta a registraci HttpClient pomocí MicrosoftIdentityMessageHandler:

   using Microsoft.AspNetCore.Authentication.OpenIdConnect;
   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();
   

3. Získejte token a volejte chráněné rozhraní API pomocí nakonfigurovaného httpClient. Pomocí WithAgentIdentity nebo WithAgentUserIdentity můžete zadat identifikaci agenta nebo uživatelský účet agenta.

   • V případě WithAgentIdentity buď zavoláte rozhraní API pomocí tokenu pouze pro aplikaci (autonomního agenta), nebo jménem uživatele (interaktivního agenta).

     Pokud chcete volat rozhraní API pouze pomocí tokenu pro aplikaci pro identitu agenta, nastavte RequestAppToken na hodnotu 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
             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();
         }
     }
     

     Pokud chcete rozhraní API volat jménem uživatele pro identitu agenta, nenastavujte RequestAppToken a ani ho explicitně nenastavujte na 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
             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();
         }
     }
     

   • Pokud chcete použít WithAgentUserIdentity, můžete zadat hlavní název uživatele (UPN) nebo OID k identifikaci uživatelského účtu agenta.

     // Create request with agent's user account identity authentication with UPN
     public async Task<string> CallApiWithAgentUserIdentityByUpn(string agentIdentity, string userUpn)
     {
     
         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's user account identity authentication with OID
     public async Task<string> CallApiWithAgentUserIdentityByOid(string agentIdentity, string userOid)
     {
     
         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();
     }
     

Použijte IAuthorizationHeaderProvider

1. Nainstalujte požadovaný balíček NuGet:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Nakonfigurujte služby pro přidání ověřování s identitami agenta:

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

   • Konfigurovat přihlašovací údaje pro ověřování v appsettings.json

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

3. Získejte a extrahujte přístupový token a pak volejte webové rozhraní API.

   • V případě WithAgentIdentity buď zavoláte rozhraní API pomocí tokenu pouze pro aplikaci (autonomního agenta), nebo jménem uživatele (interaktivního agenta).

     • V případě scénáře pouze tokenu aplikace použijte CreateAuthorizationHeaderForAppAsync metodu.
     • Pro scénář tokenu on-behalf-of (OBO) použijte CreateAuthorizationHeaderForUserAsync metodu

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

   • V WithAgentUserIdentity, voláte rozhraní API jménem uživatele pomocí jeho hlavního názvu uživatele (UPN) nebo identifikátoru OID.

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

Související obsah

• Microsoft Identity Web
• Volací rozhraní API pro Microsoft Graph
• Volají Sady Azure SDK