Memanggil API kustom dari agen menggunakan .NET

Ada beberapa cara untuk memanggil API kustom dari agen. Bergantung pada skenario Anda, Anda dapat menggunakan IDownstreamApi, , MicrosoftIdentityMessageHandleratau IAuthorizationHeaderProvider. Panduan ini menjelaskan berbagai pendekatan untuk memanggil API yang dilindungi Anda sendiri dengan ketiga cara tersebut.

Untuk memanggil API dari agen, Anda perlu mendapatkan token akses yang dapat digunakan agen untuk mengautentikasi dirinya ke API. Sebaiknya gunakan Microsoft. Identity.Web SDK untuk .NET memanggil API web Anda. SDK ini menyederhanakan proses memperoleh dan memvalidasi token. Untuk bahasa lain, gunakan Microsoft Entra ID Auth SDK (sidecar).

Prasyarat

• Identitas agen dengan izin yang sesuai untuk memanggil API target. Anda memerlukan pengguna untuk proses alur atas nama.
• Akun pengguna agen dengan izin yang sesuai untuk memanggil API target.

Memutuskan pendekatan mana yang akan digunakan berdasarkan skenario Anda

Tabel berikut ini membantu Anda memutuskan pendekatan mana yang akan digunakan. Untuk sebagian besar skenario, sebaiknya gunakan IDownstreamApi.

Pendekatan	Kompleksitas	Fleksibilitas	Kasus Penggunaan
IDownstreamApi	Rendah	Medium	REST API standar dengan konfigurasi
MicrosoftIdentityMessageHandler	Medium	Tinggi	HttpClient dengan Direct Injection (DI) dan alur yang dapat disusun
IAuthorizationHeaderProvider	Tinggi	Sangat Tinggi	Kontrol penuh atas permintaan HTTP

Menggunakan IDownstreamApi

IDownstreamApi adalah cara yang disukai untuk memanggil API yang dilindungi di antara tiga opsi. Ini sangat dapat dikonfigurasi dan memerlukan perubahan kode minimal. Ini juga menawarkan akuisisi token otomatis.

Gunakan IDownstreamApi saat Anda memerlukan item yang tercantum berikut ini:

• Anda memanggil REST API standar
• Anda menginginkan pendekatan berbasis konfigurasi
• Anda memerlukan serialisasi/deserialisasi otomatis
• Anda ingin menulis kode minimal

Menggunakan MicrosoftIdentityMessageHandler

MicrosoftIdentityMessageHandler dari Microsoft.Identity.Web.TokenAcquisition adalah handler pendelegasian yang menambahkan autentikasi ke permintaan HttpClient. Gunakan ini saat Anda memerlukan fungsionalitas HttpClient penuh dengan akuisisi token otomatis.

Microsoft.Identity.Web.TokenAcquisition sudah dirujuk oleh Microsoft.Identity.Web.AgentIdentities.

Gunakan MicrosoftIdentityMessageHandler saat Anda memerlukan item yang tercantum berikut ini:

• Anda memerlukan kontrol halus atas permintaan HTTP
• Anda ingin membuat beberapa pengendali pesan
• Anda mengintegrasikan dengan kode berbasis HttpClient yang ada
• Anda memerlukan akses ke HttpResponseMessage mentah

Menggunakan IAuthorizationHeaderProvider

IAuthorizationHeaderProvider dari Microsoft. Identity.Web memberi Anda akses langsung ke header otorisasi untuk kontrol penuh atas permintaan HTTP. Ini berarti Anda dapat menyesuaikan proses autentikasi agar sesuai dengan kebutuhan Anda, termasuk menambahkan atau memodifikasi header seperlunya. Metode ini juga memungkinkan Anda menggunakan pustaka HTTP kustom untuk melakukan panggilan API.

Gunakan IAuthorizationHeaderProvider saat Anda memerlukan item yang tercantum berikut ini:

• Anda memerlukan kontrol penuh atas konstruksi permintaan HTTP
• Anda mengintegrasikan dengan API HTTP nonstandar
• Anda perlu menggunakan HttpClient tanpa DI
• Anda sedang membangun abstraksi HTTP kustom

Memanggil API Anda

Setelah menentukan apa yang berfungsi untuk Anda, lanjutkan untuk memanggil API web kustom Anda.

Peringatan

Rahasia klien tidak boleh digunakan sebagai kredensial klien di lingkungan produksi untuk cetak biru identitas agen karena risiko keamanan. Sebagai gantinya, gunakan metode autentikasi yang lebih aman seperti kredensial identitas gabungan (FIC) dengan identitas terkelola atau sertifikat klien. Metode ini memberikan keamanan yang ditingkatkan dengan menghilangkan kebutuhan untuk menyimpan rahasia sensitif langsung dalam konfigurasi aplikasi Anda.

Menggunakan IDownstreamApi

1. Instal paket NuGet yang diperlukan:

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

2. Konfigurasikan opsi kredensial token dan API Anda di 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. Konfigurasikan layanan Anda untuk menambahkan dukungan API hilir:

   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. Panggil API terproteksi Anda menggunakan IDownstreamApi. Saat memanggil API, Anda dapat menentukan identitas agen atau identitas akun pengguna agen menggunakan WithAgentIdentity metode atau WithAgentUserIdentity . IDownstreamApi secara otomatis menangani akuisisi token dan melampirkan token akses ke permintaan.

   • Untuk WithAgentIdentity, Anda dapat memanggil API menggunakan token aplikasi saja (agen otonom) atau atas nama pengguna (agen interaktif).

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

   • Untuk WithAgentUserIdentity, Anda dapat menentukan Nama Prinsipal Pengguna (UPN) atau Identitas Objek (OID) untuk mengidentifikasi akun pengguna agen.

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

Menggunakan MicrosoftIdentityMessageHandler

1. Instal paket NuGet yang diperlukan:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Konfigurasikan layanan Anda untuk menambahkan autentikasi dengan identitas agen dan mendaftarkan HttpClient dengan 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. Dapatkan token dan panggil API yang dilindungi menggunakan HttpClient yang dikonfigurasi. Anda dapat menentukan identitas agen atau akun pengguna agen menggunakan WithAgentIdentity metode atau WithAgentUserIdentity .

   • Untuk WithAgentIdentity, Anda dapat memanggil API menggunakan token aplikasi saja (agen otonom) atau atas nama pengguna (agen interaktif).

     Untuk memanggil API menggunakan token aplikasi hanya untuk identitas agen, atur RequestAppToken ke 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();
         }
     }
     

     Untuk memanggil API atas nama pengguna untuk identitas agen, jangan atur RequestAppToken atau atur secara eksplisit ke 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();
         }
     }
     

   • Untuk menggunakan WithAgentUserIdentity, Anda dapat menentukan UPN atau OID untuk mengidentifikasi akun pengguna agen.

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

Menggunakan IAuthorizationHeaderProvider

1. Instal paket NuGet yang diperlukan:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Konfigurasikan layanan Anda untuk menambahkan autentikasi dengan identitas agen:

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

   • Mengonfigurasi kredensial autentikasi di appsettings.json

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

3. Dapatkan dan ekstrak token akses lalu panggil API web.

   • Untuk WithAgentIdentity, Anda dapat memanggil API menggunakan token aplikasi saja (agen otonom) atau atas nama pengguna (agen interaktif).

     • Untuk skenario token khusus aplikasi, gunakan CreateAuthorizationHeaderForAppAsync metode .
     • Untuk skenario token atas nama (OBO), gunakan metode 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> 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);
         }
     }
     

   • Untuk WithAgentUserIdentity, Anda memanggil API atas nama pengguna menggunakan UPN atau OID mereka.

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

Konten terkait

• Microsoft Identity Web
• Memanggil API Microsoft Graph
• Memanggil Azure SDK