Вызов пользовательских API из агента с помощью .NET

Существует несколько способов вызова пользовательских API из агента. В зависимости от вашего сценария можно использовать либо IDownstreamApi, MicrosoftIdentityMessageHandlerлибо IAuthorizationHeaderProvider. В этом руководстве описываются различные подходы к вызову собственных защищенных API всех трех способов.

Чтобы вызвать API из агента, необходимо получить маркер доступа, который агент может использовать для проверки подлинности в API. Мы рекомендуем использовать Microsoft.Identity.Web SDK для вызова ваших веб-API в .NET. Этот пакет SDK упрощает процесс получения и проверки маркеров. Для других языков используйте пакет SDK аутентификации Microsoft Entra ID (sidecar).

Необходимые условия

• Удостоверение агента с соответствующими разрешениями для вызова целевого API. Вам нужен пользователь для потока от имени.
• Учетная запись пользователя агента с соответствующими разрешениями для вызова целевого API.

Определите, какой подход следует использовать в зависимости от вашего сценария

В следующей таблице показано, какой подход следует использовать. Для большинства сценариев рекомендуется использовать IDownstreamApi.

Подход	Сложность	Гибкость	Вариант использования
IDownstreamApi	Низкий	Средний	стандартный REST API с конфигурацией
MicrosoftIdentityMessageHandler	Средний	Высокий	HttpClient с прямой внедрением (DI) и компонуемым конвейером
IAuthorizationHeaderProvider	Высокий	Очень высокий	Полный контроль над HTTP-запросами

Использование IDownstreamApi

IDownstreamApi — предпочтительный способ вызова защищенного API среди трех вариантов. Он очень настраивается и требует минимальных изменений кода. Он также предлагает автоматическое получение маркеров.

Используйте, IDownstreamApi если вам нужны следующие перечисленные элементы:

• Вы вызываете стандартные REST API
• Вам нужен ориентированный на конфигурацию подход
• Требуется автоматическая сериализация и десериализация
• Вы хотите написать минимальный код

Использование MicrosoftIdentityMessageHandler

MicrosoftIdentityMessageHandler из пакета Microsoft.Identity.Web.TokenAcquisition — это делегирующий обработчик, который добавляет аутентификацию в запросы HttpClient. Используйте это, если требуется вся функциональность HttpClient с автоматическим получением токенов.

Пакет Microsoft.Identity.Web.TokenAcquisition уже указан в Microsoft.Identity.Web.AgentIdentities.

Используйте, MicrosoftIdentityMessageHandler если вам нужны следующие перечисленные элементы:

• Вам нужен точный контроль над HTTP-запросами
• Вы хотите создать несколько обработчиков сообщений
• Вы интегрируете с существующим кодом на основе HttpClient
• Вам нужен доступ к необработанным HttpResponseMessage

Используйте IAuthorizationHeaderProvider

IAuthorizationHeaderProvider из Microsoft.Identity.Web предоставляет прямой доступ к заголовкам авторизации, обеспечивая полный контроль над HTTP-запросами. Это означает, что процесс проверки подлинности можно настроить в соответствии с вашими потребностями, включая добавление или изменение заголовков при необходимости. Этот метод также позволяет использовать пользовательские библиотеки HTTP для вызова API.

Используйте, IAuthorizationHeaderProvider если вам нужны следующие перечисленные элементы:

• Вам нужен полный контроль над построением HTTP-запроса
• Вы интегрируете нестандартные HTTP API
• Необходимо использовать HttpClient без DI.
• Вы создаете пользовательские абстракции HTTP

Вызовите ваш API

После определения того, что работает для вас, перейдите к вызову пользовательского веб-API.

Предупреждение

Секреты клиента не должны использоваться в качестве учетных данных клиента в рабочих средах для схем удостоверений агента из-за рисков безопасности. Вместо этого используйте более безопасные методы проверки подлинности, такие как учетные данные федеративной идентификации (FIC) с управляемыми идентификациями или клиентские сертификаты. Эти методы обеспечивают повышенную безопасность, устраняя необходимость хранения конфиденциальных секретов непосредственно в конфигурации приложения.

Использование IDownstreamApi

1. Установите необходимый пакет NuGet:

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

2. Настройте параметры учетных данных токена и ваши API в 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. Настройте службы для добавления поддержки нижестоящего 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();
   

4. Вызов защищенного API с помощью IDownstreamApi. При вызове API можно указать удостоверение агента или удостоверение агентского аккаунта пользователя, используя методы WithAgentIdentity или WithAgentUserIdentity. IDownstreamApi автоматически обрабатывает получение токена и присоединяет токен доступа к запросу.

   • Для WithAgentIdentity вы вызываете 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) или идентификатор объекта (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);
         }
     
     }
     

Использование MicrosoftIdentityMessageHandler

1. Установите необходимый пакет NuGet:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Настройте службы для добавления проверки подлинности с помощью удостоверений агента и регистрации 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();
   

3. Получите токен и обратитесь к защищённому API, используя настроенный HttpClient. Вы можете указать идентификатор агента или учетную запись пользователя агента с помощью методов WithAgentIdentity или WithAgentUserIdentity.

   • Для WithAgentIdentity вы вызываете API, используя только токен приложения (автономный агент) или от имени пользователя (интерактивный агент).

     Чтобы вызвать 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();
         }
     }
     

     Чтобы вызвать 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's user account 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's user account 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();
     }
     

Используйте IAuthorizationHeaderProvider

1. Установите необходимый пакет NuGet:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Настройте службы для добавления проверки подлинности с помощью удостоверений агента:

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

3. Получите и извлеките маркер доступа, а затем вызовите веб-API.

   • Для WithAgentIdentity вы вызываете 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, вы вызываете API от имени пользователя, используя их UPN или 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> 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);
         }
     }       
     

Связанный контент

• веб-сайт удостоверений Microsoft
• Call Microsoft Graph API
• Вызов Azure SDKs