Karşılaştırma: Aracı Kimliği için Microsoft Entra SDK vs. In-Process Microsoft.Identity.Web

Bu kılavuz, uygulamalarınızda kimlik doğrulamasını ele almak için kullanılan Aracı Kimliği için Microsoft Entra SDK'sı ile süreç içi Microsoft.Identity.Web kitaplığı arasındaki farkları belirlemenize yardımcı olur. Microsoft. Identity.Web kitaplığı, en yüksek performans için doğrudan .NET uygulamalarıyla tümleştirilir. Aracı Kimliği için Microsoft Entra SDK'sı ayrı bir kapsayıcı olarak çalışır ve HTTP API'leri aracılığıyla herhangi bir programlama dilini destekler. Doğru yaklaşımı seçmek, uygulamanızın mimarisine, diline ve dağıtım ortamına bağlıdır.

Mimari farklılıklar

Temel fark , kimlik doğrulama mantığının yürütüldüğü yerdedir. Microsoft. Identity.Web, uygulama işleminizde çalışır. Aracı Kimliği için Microsoft Entra SDK'sı, uygulamanızla birlikte bağımsız bir hizmet olarak çalışır. Bu mimari seçim, geliştirme iş akışı ve operasyonel karmaşıklık gibi faktörleri etkiler.

Görünüş Microsoft.Identity.Web (In-Process) Aracı Kimliği için Microsoft Entra SDK (İşlem Dışı)
İşlem Sınırı Doğrudan yöntem çağrılarını ve paylaşılan yapılandırmayı etkinleştirerek uygulamanızla aynı işlemi, belleği ve yaşam döngüsünü paylaşır Tam yalıtımı korur, yalnızca HTTP API'leri aracılığıyla iletişim kurar ve kendi kaynaklarını bağımsız olarak yönetir
Dil Kavrama Kimlik doğrulama stratejinizi .NET sıkı bir şekilde bağlayarak kimlik doğrulamasına ihtiyaç duyduğunuz her yerde C# deneyimi ve .NET çalışma zamanı gerektirir Kimlik doğrulamasını uygulamanızın teknoloji yığınından ayırır ve Python, Node.js, Go veya HTTP özellikli herhangi bir dille aynı derecede etkili bir şekilde çalışan dil bağımsız bir HTTP arabirimini kullanıma sunar.
Dağıtım Modeli Uygulama ikili dosyanıza eklenmiş NuGet paketleri olarak dağıtılır ve monolitik dağıtım birimi oluşturulur Bağımsız sürüm oluşturma, ölçeklendirme ve uygulama kodunuzu etkilemeden kimlik doğrulama mantığı güncelleştirmelerini etkinleştiren ayrı bir kapsayıcı görüntüsü olarak dağıtır

Microsoft.Identity.Web (işlem içi)

Bu kod parçacığı, Microsoft.Identity.Web'in doğrudan bir ASP.NET Core uygulamasıyla tümleştirilmesini gösterir.

// Startup configuration
services.AddMicrosoftIdentityWebApiAuthentication(Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("Graph", Configuration.GetSection("DownstreamApis:Graph"))
    .AddInMemoryTokenCaches();

// Usage in controller
public class MyController : ControllerBase
{
    private readonly IDownstreamApi _downstreamApi;
    
    public MyController(IDownstreamApi downstreamApi)
    {
        _downstreamApi = downstreamApi;
    }
    
    public async Task<ActionResult> GetUserData()
    {
        var user = await _downstreamApi.GetForUserAsync<User>("Graph", 
            options => options.RelativePath = "me");
        return Ok(user);
    }
}

Aracı Kimliği için Microsoft Entra SDK (İşlem Dışı)

Bu kod parçacığı, HTTP kullanarak bir Node.js uygulamasından Aracı Kimliği için Microsoft Entra SDK'sının nasıl çağrılduğunu gösterir. SDK'nın /DownstreamApi uç noktasına yapılan çağrı, üst bilgideki Authorization OBO akışları için gelen belirteci geçirme dahil olmak üzere belirteç alma ve aşağı akış API çağrılarını işler:

// Configuration
const SidecarUrl = process.env.SIDECAR_URL || "http://localhost:5000";

// Usage in application
async function getUserData(incomingToken: string) {
  const response = await fetch(
    `${SidecarUrl}/DownstreamApi/Graph?optionsOverride.RelativePath=me`,
    {
      headers: {
        'Authorization': `Bearer ${incomingToken}`
      }
    }
  );
  
  const result = await response.json();
  return JSON.parse(result.content);
}

Özellik karşılaştırması

Özellik Microsoft. Identity.Web Aracı Kimliği için Microsoft Entra SDK
Dil Desteği Yalnızca C# / .NET Herhangi bir dil (HTTP)
Dağıtım İşlem sırasında kullanılan kitaplık Ayrı kap
Belirteç Alma Doğrudan MSAL.NET HTTP API aracılığıyla
Belirteç Önbelleğe Alma Bellek içi, dağıtık Bellekte bulunan, dağıtılmış
OBO Akışı Yerel destek HTTP uç noktası aracılığıyla
İstemci Kimlik Bilgileri Yerel destek HTTP uç noktası aracılığıyla
Yönetilen Kimlik Doğrudan destek Doğrudan destek
Aracı Kimlikleri Uzantılar aracılığıyla Sorgu parametreleri
Belirteç Doğrulama Middleware /Validate uç noktası
Aşağı akış API'si IDownstreamApi /DownstreamApi uç noktası
Microsoft Graph Graph SDK tümleştirmesi DownstreamApi aracılığıyla
Performans İşlem sırasında (en hızlı) HTTP ek yükü
Configuration appsettings.json ve kod appsettings.json ve ortam değişkenleri
Hata ayıklama Standart .NET hata ayıklama Kapsayıcı hata ayıklama
Çalışırken Yeniden Yükleme .NET Çalışırken Yeniden Yükleme Kapsayıcı yeniden başlatma
Paket Güncelleştirmeleri NuGet paketleri Konteyner görüntüleri
Lisans MIT MIT

Her yaklaşımın ne zaman kullanılacağı

Microsoft.Identity.Web ve Aracı Kimliği için Microsoft Entra SDK'sı arasında karar vermek, uygulamanızın gereksinimlerine, mimarisine ve dağıtım stratejisine bağlıdır. Gereksinimlerinize bağlı olarak, bir yaklaşım diğerinden daha uygun olabilir. Aşağıdaki yönergeler, bilinçli bir karar verme konusunda size yardımcı olabilir.

Scenario Microsoft.Identity.Web (In-Process) Aracı Kimliği için Microsoft Entra SDK (İşlem Dışı)
Uygulama Yığını .NET uygulamaları için özel olarak
• ASP.NET Core Web API'leri
• ASP.NET Core Web Apps
• .NET Çalışan Hizmetleri
• Blazor uygulamaları
• Daemon uygulamaları		 Çok dilli mikro hizmetler
• Node.js, Python, Go, Java hizmetleri
• Çok dilli mimariler
• .NET olmayan hizmetler
• Eski sistem tümleştirmesi
Performans Gereksinimleri Performans kritiktir.
• Yüksek aktarım hızı senaryoları
• Gecikmeye duyarlı işlemler
• Her milisaniyelik sayımlar		 HTTP ek yükünü tolere edebilir
• ~1-5ms ek gecikme kabul edilebilir
• Aktarım hızı, kimlik doğrulaması tarafından kısıtlanmaz
Tümleştirme Gereksinimleri Derin tümleştirme gerekiyor
• Özel MSAL.NET yapılandırması
• MSAL özelliklerine doğrudan erişim
• Gelişmiş belirteç önbellek stratejileri		 Standartlaştırılmış tümleştirme
• HTTP API yeterli
• Hizmetler arasında tutarlı kimlik doğrulama desenleri
Geliştirme Deneyimi Hızlı geliştirme
• Hızlı prototip oluşturma
• Geliştirme için sıcak yeniden yükleme
• Standart .NET hata ayıklama		 Kapsayıcı tabanlı geliştirme
• Değişiklikler için kapsayıcı yeniden başlatma
• Kapsayıcı hata ayıklaması gerekiyor
Ekip ve Mimari Tek dilli yığın
• C#/.NET'da ekip uzmanlığı
• Çok dilli gereksinimler yoktur		 Teknoloji çeşitliliği
• Çerçevelerin ve dillerin karışımı
• Polyglot takım yapısı
Dağıtım Modeli Monolitik dağıtımlar
• Tek uygulama dağıtımı
• Geleneksel barındırma modelleri		 Kapsayıcılı dağıtımlar
• Kubernetes ortamları
• Docker Compose kurulumları
• Hizmet ağı mimarileri
Operations Eşleştirilmiş kimlik doğrulama güncelleştirmeleri
• Kimlik doğrulama değişiklikleri için uygulamanın yeniden derlenmesi gerekir
• Uygulamayla paylaşılan yaşam döngüsü		 Operasyonel avantajlar
• Kimlik doğrulama mantığının bağımsız olarak ölçeklenmesi
• Kimlik doğrulama güncelleştirmelerini uygulama kodundan ayırın
• Kimlik doğrulamasının merkezi olarak izlenmesi

Geçiş kılavuzu

Microsoft.Identity.Web'den Microsoft Entra SDK'sına, AgentID için geçiş.

Bazı senaryolarda, kimlik doğrulaması için Agent ID kullanarak Microsoft Entra SDK'sından yararlanmak amacıyla, Microsoft.Identity.Web kullanan mevcut bir .NET uygulamasını geçirmek isteyebilirsiniz. Geçiş nedenleri arasında çok dilli bir mimari benimseme, hizmetler arasında kimlik doğrulamasını standartlaştırma veya kapsayıcılı dağıtım modeline geçme sayılabilir.

Bu değişikliği yapmanız için dikkatli bir değerlendirme ve planlama gerekir. Bu bölüm, uygulamanızı geçirmenize yardımcı olacak kod örneklerini içeren üst düzey bir geçiş yolu sağlar.

Dikkat

Microsoft, Microsoft.Identity.Web’den, AgentID için Microsoft Entra SDK’sına geçiş yapmanızı önermemektedir. Bu değişikliği yapmayı seçerseniz, aşağıdaki örnekler diğer dillerde ve çerçevelerde benzer kavramları gösterir.

1. Adım: SDK kapsayıcısı dağıtma

İlk olarak, SDK kapsayıcısını podunuza ekleyin:

# Before: Single ASP.NET Core container
containers:
- name: app
  image: myregistry/myapp:latest

# After: App + Microsoft Entra SDK for AgentID
containers:
- name: app
  image: myregistry/myapp:latest
  env:
  - name: SIDECAR_URL
    value: "http://localhost:5000"

- name: sidecar
  image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
  env:
  - name: AzureAd__TenantId
    value: "your-tenant-id"
  - name: AzureAd__ClientId
    value: "your-client-id"

2. Adım: Yapılandırmayı Taşıma

Ardından yapılandırmanızı appsettings.json ortam değişkenlerine aktarabilirsiniz:

appsettings.json'dan Önce

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id"
  },
  "DownstreamApis": {
    "Graph": {
      "BaseUrl": "https://graph.microsoft.com/v1.0",
      "Scopes": "User.Read Mail.Read", 
      "RelativePath": "/me"
    }
  }
}

Sonra (Kubernetes ConfigMap / Ortam Değişkenleri)

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "your-tenant-id"
  AzureAd__ClientId: "your-client-id"
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  DownstreamApis__Graph__RelativePath: "/me"

3. Adım: Uygulama kodunu güncelleştirme

Microsoft.Identity.Web'e yapılan işlem içi çağrıların tüm örneklerini bulun ve bunları Aracı Kimlik uç noktaları için Microsoft Entra SDK'ya yapılan HTTP çağrılarıyla değiştirin.

Önce (C# with IDownstreamApi):

public class UserController : ControllerBase
{
    private readonly IDownstreamApi _downstreamApi;
    
    public UserController(IDownstreamApi downstreamApi)
    {
        _downstreamApi = downstreamApi;
    }
    
    [HttpGet]
    public async Task<ActionResult<User>> GetMe()
    {
        var user = await _downstreamApi.GetForUserAsync<User>(
            "Graph",
            options => options.RelativePath = "me"
        );
        return Ok(user);
    }
}

Sonra (HTTP istemcisi ile herhangi bir dil):

Aşağıdaki kod parçacığında, kullanıcı verilerini almak için /DownstreamApi uç noktasını kullanarak Aracı Kimliği için Microsoft Entra SDK'sına çağrılar görürsünüz. Örnekler C# ve TypeScript'te sağlanır.

public class UserController : ControllerBase
{
    private readonly HttpClient _httpClient;
    private readonly string _SidecarUrl;
    
    public UserController(IHttpClientFactory httpClientFactory, IConfiguration config)
    {
        _httpClient = httpClientFactory.CreateClient();
        _SidecarUrl = config["SIDECAR_URL"];
    }
    
    [HttpGet]
    public async Task<ActionResult<User>> GetMe()
    {
        var inboundAuthorizationHeader = Request.Headers["Authorization"].ToString();
        // this validates the inbound authorization header and calls the downstream API.
        // If you don't call a downstream API, Do validate the inbound authorization header 
        // (calling the /Validate endpoint)
        var request = new HttpRequestMessage(
            HttpMethod.Get,
            $"{_SidecarUrl}/DownstreamApi/Graph?optionsOverride.RelativePath=me"
        );
        request.Headers.Add("Authorization", inboundAuthorizationHeader);
        
        var response = await _httpClient.SendAsync(request);
        var result = await response.Content.ReadFromJsonAsync<SidecarResponse>();
        var user = JsonSerializer.Deserialize<User>(result.Content);
        return Ok(user);
    }
}

TypeScript

TypeScript'te aşağıdaki gibi aynı mantığı uygulayabilirsiniz:

export async function getMe(incomingToken: string): Promise<User> {
  const SidecarUrl = process.env.SIDECAR_URL!;
  
  const response = await fetch(
    `${SidecarUrl}/DownstreamApi/Graph?optionsOverride.RelativePath=me`,
    {
      headers: {
        'Authorization': incomingToken
      }
    }
  );
  
  const result = await response.json();
  return JSON.parse(result.content) as User;
}

4. Adım: Microsoft.Identity.Web bağımlılıklarını kaldırma

Önceki adımları tamamladıktan sonra, Microsoft.Identity.Web için NuGet paketlerini projenizden kaldırarak uygulamanızı düzenleyin.

<!-- Remove these from .csproj -->
<PackageReference Include="Microsoft.Identity.Web" Version="..." />
<PackageReference Include="Microsoft.Identity.Web.MicrosoftGraph" Version="..." />
<PackageReference Include="Microsoft.Identity.Web.DownstreamApi" Version="..." />

Yine de uygulamanızdaki belirteçleri doğrulamak istiyorsanız, özgün kimlik doğrulama yapılandırmasını kaldırmanız gerekmez. Bunun yerine, doğrulamayı tamamen AgentID için Microsoft Entra SDK'sına devredebilirsiniz.

// Remove from Program.cs or Startup.cs
services.AddMicrosoftIdentityWebApiAuthentication(Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("Graph", Configuration.GetSection("DownstreamApis:Graph"))
    .AddInMemoryTokenCaches();

5. Adım: Test ve doğrulama

  1. Birim testleri: Testleri, SDK'ya yapılacak HTTP çağrılarını taklit edecek şekilde güncelleyin.
  2. Tümleştirme testleri: Hazırlamada SDK iletişimlerini test edin.
  3. Performans testleri: HTTP ek yükü etkisini ölçün.
  4. Güvenlik testleri: Belirteç işlemeyi ve ağ ilkelerini doğrulayın.

Performansla ilgili dikkat edilmesi gerekenler

SDK ek yükü

Aracı Kimliği için Microsoft Entra SDK'sı HTTP iletişim yükünü getirir:

Performans Faktörü Etki Risk Azaltma Stratejisi
Latency Localhost iletişimi için istek başına yaklaşık 1-5 ms Bağlantı ek yükünü azaltmak için HTTP/2 kullanın.
Throughput HTTP bağlantı havuzunun sınırlamaları ile sınırlıdır HTTP bağlantılarını yeniden kullanmak için bağlantı havuzu uygulama.
Memory Ek kapsayıcı bellek üst yükü Yeterli SDK kaynak ayırmasını sağlayın.
İstek Verimliliği Karmaşık işlemler için birden çok gidiş dönüş Mümkün olduğunda birden çok işlemi birleştirmek için toplu istekler kullanın.
Belirteç Performansı Yinelenen belirteç alma ek yükü En iyi performans için SDK'nın belirteç önbelleğinden yararlanın.

Süreç İçi performans

Microsoft.Identity.Web kullanımı, uygulamanızla aynı işlem içinde çalıştığından düşük ek yüke sahiptir. HTTP sınırlamaları olmadan mikrosaniyelik gecikme süresi ve paylaşılan işlem belleği ile yerel yöntem çağrıları sağlar. Performans kritik olduğunda, işlem içi tümleştirme en uygun seçenektir. Ancak AgentID'nin esnekliğine ve dilden bağımsız tasarımına yönelik Microsoft Entra SDK'sı birçok senaryoda performans dengelerini aşabilir.

Aşağıdaki tabloda, işlem içi kullanım ve Aracı Kimliği (İşlem Dışı) kullanımı için Microsoft Entra SDK'sı için bazı performans ve maliyet karşılaştırmaları gösterilmektedir:

Maliyetle ilgili dikkat edilmesi gerekenler

Maliyet Faktörü Microsoft.Identity.Web (In-Process) Aracı Kimliği için Microsoft Entra SDK (İşlem Dışı)
Hesaplamak Uygulama işleminde en az ek CPU ve bellek Pod başına ek kapsayıcı kaynakları.
Network Ek yük yok En az düzeyde localhost iletişimi.
Depolama NuGet paket boyutu (yaklaşık 10 MB) Kapsayıcı görüntü depolama.
Yönetim Ek yük yok Kapsayıcı orkestrasyon ek yükü.

Maliyet örneği

128 MiB/100m SDK yapılandırmasına sahip 10 kopya için:

Resource İşlemde Aracı Kimliği için Microsoft Entra SDK
Memory Yaklaşık 0 MB ek 10 × 128 MiB = 1,28 GB
CPU Yaklaşık 0% ek 10 × 100m = 1 çekirdek
Depolama Dağıtım başına yaklaşık 10 MB Düğüm başına kapsayıcı imaj boyutu

Destek ve bakım

Görünüş Microsoft. Identity.Web Aracı Kimliği için Microsoft Entra SDK
Updates NuGet paket güncelleştirmeleri Konteyner görüntüsü güncellemeleri
Kırıcı Değişiklikler Paket sürümleme yoluyla Kapsayıcı etiketleri aracılığıyla
Hata Düzeltmeleri Derleme zamanı entegrasyonu Çalışma zamanı kapsayıcı güncelleştirmeleri
Güvenlik Düzeltme Ekleri Uygulamayı yeniden oluşturma Kapsayıcıyı yeniden devreye alma
Dokümantasyon Kapsamlı .NET belgeleri Bu belgeler
Community Büyük .NET topluluğu Büyüyen topluluk

Karma yaklaşım

Her iki yaklaşımı da aynı mimari içinde birleştirebilirsiniz. .NET hizmetlerinde maksimum performans gerektiğinde Microsoft.Identity.Web kullanın, .NET olmayan hizmetlerde veya dil bağımsız kimlik doğrulama desenlerine ihtiyaç duyduğunuzda ise Aracı Kimliği için Microsoft Entra SDK'sını kullanın. Bu karma strateji, tüm hizmet ekosisteminizde tutarlılığı ve esnekliği korurken kritik olduğu durumlarda performansı iyileştirmenize yardımcı olur.

Örnek mimari aşağıdaki gibidir:

graph TB
    subgraph cluster["Kubernetes Cluster"]
        subgraph netpod["<b>.NET API Pod</b>"]
            netapi["<b>.NET API</b><br/>(Microsoft.Identity.Web)"]
            style netapi fill:#0078d4,stroke:#005a9e,stroke-width:2px,color:#fff
        end
        subgraph nodepod["<b>Node.js API Pod</b>"]
            nodeapi["<b>Node.js API</b>"]
            sidecar["<b>Microsoft Entra SDK for AgentID</b>"]
            style nodeapi fill:#68a063,stroke:#4a7c45,stroke-width:2px,color:#fff
            style sidecar fill:#f2711c,stroke:#d85e10,stroke-width:2px,color:#fff
        end
    end
    style cluster fill:#f0f0f0,stroke:#333,stroke-width:3px
    style netpod fill:#e8f4f8,stroke:#0078d4,stroke-width:2px
    style nodepod fill:#e8f4e8,stroke:#68a063,stroke-width:2px

İlgili içerik

  • Last updated on