Wywoływanie niestandardowych interfejsów API z agenta przy użyciu .NET

Istnieje wiele sposobów wywoływania niestandardowych interfejsów API z agenta. W zależności od scenariusza można użyć polecenia IDownstreamApi, MicrosoftIdentityMessageHandlerlub IAuthorizationHeaderProvider. W tym przewodniku wyjaśniono różne podejścia do wywoływania własnych chronionych interfejsów API na wszystkie trzy sposoby.

Aby wywołać interfejs API z agenta, należy uzyskać token dostępu, którego agent może użyć do uwierzytelnienia się w interfejsie API. Zalecamy użycie Microsoft. Identity.Web SDK for .NET do wywoływania internetowych interfejsów API. Ten zestaw SDK upraszcza proces uzyskiwania i weryfikowania tokenów. Dla innych języków użyj zestawu SDK uwierzytelniania Microsoft Entra ID (sidecar).

Wymagania wstępne

• Tożsamość agenta z odpowiednimi uprawnieniami do wywoływania docelowego interfejsu API. Potrzebujesz użytkownika do procesu wykonywanego w imieniu innych.
• Konto użytkownika agenta z odpowiednimi uprawnieniami do wywoływania docelowego interfejsu API.

Zdecyduj, które podejście ma być używane w zależności od scenariusza

Poniższa tabela ułatwia podjęcie decyzji o tym, które podejście ma być używane. W przypadku większości scenariuszy zalecamy użycie polecenia IDownstreamApi.

Metoda	Złożoność	Elastyczność	Przypadek użycia
IDownstreamApi	Low	Średni	Standardowe interfejsy API REST z konfiguracją
MicrosoftIdentityMessageHandler	Średni	High	HttpClient z bezpośrednim wstrzyknięciem (DI) i potokiem komponowalnym
IAuthorizationHeaderProvider	High	Bardzo wysoka	Pełna kontrola nad żądaniami HTTP

Korzystanie z interfejsu IDownstreamApi

IDownstreamApi jest preferowanym sposobem wywoływania chronionego interfejsu API między trzema opcjami. Jest on wysoce konfigurowalny i wymaga minimalnych zmian w kodzie. Oferuje również automatyczne pozyskiwanie tokenów.

Użyj IDownstreamApi, gdy potrzebne są następujące elementy:

• Wywołujesz standardowe interfejsy API REST
• Potrzebujesz podejścia opartego na konfiguracji
• Potrzebna jest automatyczna serializacja/deserializacja
• Chcesz napisać minimalny kod

Korzystanie z programu MicrosoftIdentityMessageHandler

MicrosoftIdentityMessageHandler z Microsoft. Identity.Web.TokenAcquisition pakiet to program obsługi delegowania, który dodaje uwierzytelnianie do żądań HttpClient. Użyj tej funkcji, jeśli potrzebujesz pełnej funkcjonalności httpClient z automatycznym pozyskiwaniem tokenu.

Microsoft.Identity.Web.TokenAcquisition jest już przywoływany przez Microsoft.Identity.Web.AgentIdentities.

Użyj MicrosoftIdentityMessageHandler, gdy potrzebne są następujące elementy:

• Potrzebna jest szczegółowa kontrola nad żądaniami HTTP
• Chcesz utworzyć wiele programów obsługi komunikatów
• Integrujesz się z istniejącym kodem opartym na kliencie HttpClient
• Potrzebujesz dostępu do nieprzetworzonego komunikatu HttpResponseMessage

Korzystanie z elementu IAuthorizationHeaderProvider

IAuthorizationHeaderProvider z Microsoft.Identity.Web zapewnia bezpośredni dostęp do nagłówków autoryzacyjnych, co umożliwia pełną kontrolę nad żądaniami HTTP. Oznacza to, że w razie potrzeby można dostosować proces uwierzytelniania, w tym dodawać lub modyfikować nagłówki. Ta metoda umożliwia również używanie niestandardowych bibliotek HTTP do tworzenia wywołań interfejsu API.

Użyj IAuthorizationHeaderProvider, gdy potrzebne są następujące elementy:

• Potrzebna jest pełna kontrola nad tworzeniem żądań HTTP
• Współpracujesz z niestandardowymi interfejsami API HTTP
• Musisz użyć klienta HttpClient bez di
• Tworzysz niestandardowe abstrakcje HTTP

Wywołaj swoje API

Po określeniu, co działa dla Ciebie, przejdź do wywołania niestandardowego internetowego interfejsu API.

Ostrzeżenie

Tajne klucze klienta nie powinny być używane jako poświadczenia klienta w środowiskach produkcyjnych dla szablonów tożsamości agenta ze względu na zagrożenia bezpieczeństwa. Zamiast tego należy użyć bezpieczniejszych metod uwierzytelniania, takich jak poświadczenia tożsamości federacyjnej (FIC) z tożsamościami zarządzanymi lub certyfikatami klienta. Te metody zapewniają zwiększone zabezpieczenia, eliminując konieczność przechowywania poufnych wpisów tajnych bezpośrednio w ramach konfiguracji aplikacji.

Korzystanie z interfejsu IDownstreamApi

1. Zainstaluj wymagany pakiet NuGet:

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

2. Skonfiguruj opcje poświadczeń tokenu i interfejsy API w 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. Skonfiguruj usługi, aby dodać obsługę interfejsu API podrzędnego:

   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. Wywołaj chroniony interfejs API przy użyciu polecenia IDownstreamApi. Podczas wywoływania interfejsu API można określić tożsamość agenta lub tożsamość konta użytkownika agenta przy użyciu metod WithAgentIdentity lub WithAgentUserIdentity. IDownstreamApi automatycznie obsługuje pozyskiwanie tokenów i dołącza token dostępu do żądania.

   • Aby WithAgentIdentity, możesz wywołać interfejs API przy użyciu tokenu tylko dla aplikacji (agenta autonomicznego) lub w imieniu użytkownika (agenta interaktywnego).

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

   • W przypadku WithAgentUserIdentity można określić główną nazwę użytkownika (UPN) lub tożsamość obiektu (OID), aby zidentyfikować konto użytkownika 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 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);
         }
     
     }
     

Korzystanie z programu MicrosoftIdentityMessageHandler

1. Zainstaluj wymagany pakiet NuGet:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Skonfiguruj usługi w celu dodania uwierzytelniania przy użyciu tożsamości agenta i zarejestrowania klienta HttpClient za pomocą polecenia 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. Uzyskaj token i wywołaj chronione API przy użyciu skonfigurowanego HttpClient. Tożsamość agenta lub konto użytkownika agenta można określić przy użyciu metod WithAgentIdentity lub WithAgentUserIdentity.

   • Aby WithAgentIdentity, możesz wywołać interfejs API przy użyciu tokenu tylko dla aplikacji (agenta autonomicznego) lub w imieniu użytkownika (agenta interaktywnego).

     Aby wywołać API przy użyciu tokenu aplikacji dla tożsamości agenta, ustaw RequestAppToken na 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();
         }
     }
     

     Aby wywołać API w imieniu użytkownika dla tożsamości agenta, nie należy ustawiać RequestAppToken ani jawnie ustawiać 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();
         }
     }
     

   • Aby użyć WithAgentUserIdentity polecenia, możesz określić nazwę UPN lub identyfikator OID, aby zidentyfikować konto użytkownika 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();
     }
     

Korzystanie z elementu IAuthorizationHeaderProvider

1. Zainstaluj wymagany pakiet NuGet:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Skonfiguruj usługi w celu dodania uwierzytelniania przy użyciu tożsamości 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();
   

   • Konfigurowanie poświadczeń uwierzytelniania w appsettings.json

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

3. Uzyskaj i wyodrębnij token dostępu, a następnie wywołaj internetowy interfejs API.

   • Aby WithAgentIdentity, możesz wywołać interfejs API przy użyciu tokenu tylko dla aplikacji (agenta autonomicznego) lub w imieniu użytkownika (agenta interaktywnego).

     • W przypadku scenariusza z tokenem tylko aplikacji użyj metody CreateAuthorizationHeaderForAppAsync.
     • W scenariuszu tokenu on-behalf-of (OBO) użyj CreateAuthorizationHeaderForUserAsync metody

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

   • W przypadku WithAgentUserIdentity wywołujesz interfejs API w imieniu użytkownika przy użyciu ich UPN lub 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);
         }
     }       
     

Treści powiązane

• Microsoft Identity Web
• Call Microsoft Graph API
• Wywoływanie Azure SDKs