.NET kullanarak bir aracıdan özel API'leri çağırma

Bir aracıdan özel API'leri çağırmanın birden çok yolu vardır. Senaryonuza bağlı olarak , IDownstreamApiveya MicrosoftIdentityMessageHandlerkullanabilirsinizIAuthorizationHeaderProvider. Bu kılavuzda, kendi korumalı API'lerinizi çağırmak için üç yöntemin tümüne yönelik farklı yaklaşımlar açıklanmaktadır.

Bir aracıdan API çağırmak için, aracının API'de kimliğini doğrulamak için kullanabileceği bir erişim belirteci almanız gerekir. Microsoft.Identity.Web SDK'sını .NET için web API'lerinizi çağırmak üzere kullanmanızı öneririz. Bu SDK, belirteçleri alma ve doğrulama işlemini basitleştirir. Diğer diller için, aracı kimliği için Microsoft Entra aracı SDK'sını kullanın.

Önkoşullar

• Hedef API'yi çağırmak için uygun izinlere sahip bir aracı kimliği. Akış adına işlem için bir kullanıcıya ihtiyacınız vardır.
• Hedef API’yi çağırmak için uygun izinlere sahip bir ajanın kullanıcı hesabı.

Senaryonuza göre hangi yaklaşımı kullanacağınıza karar verin

Aşağıdaki tablo, hangi yaklaşımı kullanacağınıza karar vermenize yardımcı olur. Çoğu senaryo için kullanmanızı IDownstreamApiöneririz.

Yaklaşım	Karmaşıklık	Esneklik	Kullanım Örneği
IDownstreamApi	Low	Orta	Yapılandırma ile standart REST API'leri
MicrosoftIdentityMessageHandler	Orta	Yüksek	Doğrudan Ekleme (DI) ve birleştirilebilir işlem hattı ile HttpClient
IAuthorizationHeaderProvider	Yüksek	Çok Yüksek	HTTP istekleri üzerinde tam denetim

IDownstreamApi kullanma

IDownstreamApi , üç seçenek arasında korumalı API çağırmanın tercih edilen yoludur. Yüksek oranda yapılandırılabilir ve en az kod değişikliği gerektirir. Ayrıca otomatik jeton alımı da sunar.

Aşağıdaki listelenen öğelere ihtiyacınız olduğunda kullanın IDownstreamApi :

• Standart REST API'lerini çağırıyorsunuz
• Yapılandırma temelli bir yaklaşım istiyorsunuz
• Otomatik serileştirme ve seri durumdan çıkarma ihtiyacınız var.
• En az kod yazmak istiyorsunuz

MicrosoftIdentityMessageHandler kullanma

MicrosoftIdentityMessageHandler Microsoft.Identity.Web.TokenAcquisition paketi, HttpClient isteklerine kimlik doğrulaması ekleyen bir temsilci işleyicisi olarak görev yapar. Otomatik belirteç alma ile tam HttpClient işlevine ihtiyacınız olduğunda bunu kullanın.

Microsoft.Identity.Web.TokenAcquisition paketi, zaten Microsoft.Identity.Web.AgentIdentities tarafından referans alınmış.

Aşağıdaki listelenen öğelere ihtiyacınız olduğunda kullanın MicrosoftIdentityMessageHandler :

• HTTP istekleri üzerinde ayrıntılı denetime ihtiyacınız var
• Birden çok ileti işleyicisi oluşturmak istiyorsunuz
• Mevcut HttpClient tabanlı kodla tümleştiriyorsunuz
• Ham HttpResponseMessage erişiminiz olmalıdır

IAuthorizationHeaderProvider kullanın

IAuthorizationHeaderProvider Microsoft.Identity.Web, HTTP istekleri üzerinde tam denetim için yetkilendirme başlıklarına doğrudan erişim sağlar. Bu, kimlik doğrulama işlemini gerektiği gibi üst bilgileri ekleme veya değiştirme de dahil olmak üzere gereksinimlerinize uyacak şekilde özelleştirebileceğiniz anlamına gelir. Bu yöntem, API çağrıları yapmak için özel HTTP kitaplıkları kullanmanıza da olanak tanır.

Aşağıdaki listelenen öğelere ihtiyacınız olduğunda kullanın IAuthorizationHeaderProvider :

• HTTP isteği oluşturma üzerinde tam denetime ihtiyacınız var
• Standart olmayan HTTP API'leri ile entegrasyon sağlıyorsunuz
• HTTPClient'ı DI olmadan kullanmanız gerekir
• Özel HTTP soyutlamaları oluşturuyorsunuz

API'nizi çağırma

Sizin için neyin işe yaradığını belirledikten sonra özel web API'nizi çağırmaya devam edin.

Uyarı

Güvenlik risklerinden dolayı istemci sırları, ajan kimlik planları için üretim ortamlarında istemci kimlik bilgileri olarak kullanılmamalıdır. Bunun yerine, yönetilen kimliklerle veya istemci sertifikalarıyla federasyon kimlik bilgileri (FIC) gibi daha güvenli kimlik doğrulama yöntemleri kullanın. Bu yöntemler, hassas gizli dizileri doğrudan uygulama yapılandırmanızda depolama gereksinimini ortadan kaldırarak gelişmiş güvenlik sağlar.

IDownstreamApi kullanma

1. Gerekli NuGet paketini yükleyin:

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

2. appsettings.json'de belirteç kimlik bilgisi seçeneklerini ve API'lerinizi yapılandırın.

   {
     "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. Aşağı akış API desteği eklemek için hizmetlerinizi yapılandırın:

   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. Korumalı API'nizi kullanarak IDownstreamApi çağırın. API'yi çağırırken WithAgentIdentity veya WithAgentUserIdentity yöntemlerinden birini kullanarak aracı kimliğini veya kullanıcının hesap kimliğini belirtebilirsiniz. IDownstreamApi belirteç alma işlemini otomatik olarak işler ve erişim belirtecini isteğe ekler.

   • WithAgentIdentity için, API'yi ya yalnızca bir uygulama belirteci (otonom ajan) kullanarak ya da bir kullanıcı adına (etkileşimli ajan) çağırırsınız.

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

   • için WithAgentUserIdentity, aracının kullanıcı hesabını tanımlamak için Kullanıcı Asıl Adı (UPN) veya Nesne Kimliği (OID) belirtebilirsiniz.

     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 kullanma

1. Gerekli NuGet paketini yükleyin:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Hizmetlerinizi, aracı kimlikleriyle kimlik doğrulaması eklemek ve HttpClient'ı MicrosoftIdentityMessageHandler ile kaydetmek için yapılandırın.

   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. Jeton alın ve yapılandırılmış HttpClient'i kullanarak korumalı API'nizi çağırın. veya WithAgentIdentity yöntemlerini kullanarak aracı kimliğini veya aracının WithAgentUserIdentity kullanıcı hesabını belirtebilirsiniz.

   • WithAgentIdentity için, API'yi ya yalnızca bir uygulama belirteci (otonom ajan) kullanarak ya da bir kullanıcı adına (etkileşimli ajan) çağırırsınız.

     API'yi yalnızca aracı kimliği için bir uygulama belirteci kullanarak çağırmak için, RequestAppToken değişkenini true olarak ayarlayın.

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

     Bir kullanıcının adına ve aracı kimliği için API'yi çağırmak amacıyla, RequestAppToken'yi ayarlamayın veya bunu açıkça false olarak ayarlamayın.

     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 kullanmak için, aracının kullanıcı hesabını tanımlamak için UPN veya OID belirtebilirsiniz.

     // 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 kullanın

1. Gerekli NuGet paketini yükleyin:

   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

2. Hizmetlerinizi aracı kimlikleriyle kimlik doğrulaması ekleyecek şekilde yapılandırın:

   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 dosyasındaki kimlik doğrulama kimliklerini yapılandırma

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

3. Erişim belirtecini alın ve ayıklayın, ardından web API'sini çağırın.

   • WithAgentIdentity için, API'yi ya yalnızca bir uygulama belirteci (otonom ajan) kullanarak ya da bir kullanıcı adına (etkileşimli ajan) çağırırsınız.

     • Yalnızca uygulama için belirteç senaryosunda CreateAuthorizationHeaderForAppAsync yöntemini kullanın.
     • OBO belirteci senaryosu için CreateAuthorizationHeaderForUserAsync metodunu kullanın

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

   • için WithAgentUserIdentityAPI'yi UPN veya OID kullanarak bir kullanıcı adına çağırırsınız.

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

İlgili içerik

• Microsoft identity web
• Microsoft Graph API'lerini Çağır
• Call Azure SDK’ları