Porównanie: Microsoft Entra SDK for AgentID a In-Process Microsoft.Identity.Web

Ten przewodnik pomaga zidentyfikować różnice między zestawem Microsoft Entra SDK for AgentID i biblioteką Microsoft.Identity.Web do obsługi uwierzytelniania w aplikacjach. Biblioteka Microsoft.Identity.Web integruje się bezpośrednio z aplikacjami .NET w celu uzyskania maksymalnej wydajności, podczas gdy zestaw Microsoft Entra SDK for AgentID działa jako oddzielny kontener i obsługuje dowolny język programowania za pośrednictwem interfejsów API HTTP, a wybór poprawnego podejścia zależy od architektury, języka i środowiska wdrażania aplikacji.

Różnice architektury

Podstawowa różnica polega na miejscu wykonywania logiki uwierzytelniania. Microsoft.Identity.Web działa w ramach procesu aplikacji, a zestaw Microsoft Entra SDK for AgentID działa jako niezależna usługa obok aplikacji. Ten wybór architektury ma wpływ na czynniki, takie jak przepływ pracy programowania i złożoność operacyjna.

Microsoft.Identity.Web (In-Process)

Ten fragment kodu pokazuje, jak platforma Microsoft.Identity.Web integruje się bezpośrednio z aplikacją platformy ASP.NET Core:

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

Zestaw Microsoft Entra SDK dla identyfikatora agenta (poza procesem)

Ten fragment kodu pokazuje, jak wywołać zestaw Microsoft Entra SDK for AgentID z aplikacji Node.js przy użyciu protokołu HTTP. Wywołanie punktu końcowego /DownstreamApi zestawu SDK obsługuje pozyskiwanie tokenów i wywołania interfejsów API podrzędnych, w tym przekazywanie przychodzącego tokenu dla przepływów OBO w nagłówku Authorization:

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

Porównanie funkcji

Kiedy należy używać każdego podejścia

Wybór między microsoft.Identity.Web a zestawem Microsoft Entra SDK for AgentID zależy od wymagań, architektury i strategii wdrażania aplikacji. W zależności od potrzeb jedno podejście może być bardziej odpowiednie niż inne, a poniższe wskazówki mogą pomóc w podjęciu świadomej decyzji.

Wskazówki dotyczące migracji

Migracja z Microsoft.Identity.Web do Microsoft Entra SDK dla identyfikatora AgentID

W niektórych scenariuszach możesz chcieć zmigrować istniejącą aplikację .NET przy użyciu Microsoft.Identity.Web, aby skorzystać z zestawu SDK Microsoft Entra dla AgentID do uwierzytelniania. Przyczyny migracji mogą obejmować wdrożenie architektury wielojęzycznej, standaryzację uwierzytelniania między usługami lub przejście do konteneryzowanego modelu wdrażania.

Przed wykonaniem tej czynności należy dokładnie rozważyć i zaplanować. Ta część zawiera ogólną ścieżkę migracji z przykładami kodu, które ułatwiają migrację aplikacji.

Krok 1. Wdrażanie kontenera zestawu SDK

Najpierw musisz dodać kontener SDK do zasobnika.

# 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"

Krok 2. Migrowanie konfiguracji

Następnie należy przenieść konfigurację z appsettings.json do zmiennych środowiskowych:

Przed (appsettings.json)

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

Po (Kubernetes ConfigMap / Zmienne środowiskowe)

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"

Krok 3. Aktualizowanie kodu aplikacji

Znajdź wszystkie wystąpienia wywołań w procesie do microsoft.Identity.Web i zastąp je wywołaniami HTTP do zestawu Microsoft Entra SDK dla punktów końcowych AgentID:

Przed (C# z 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);
    }
}

Po (dowolny język z klientem HTTP):

W poniższym fragmencie kodu można zobaczyć wywołania Microsoft Entra SDK dla AgentID przy użyciu punktu końcowego /DownstreamApi, aby pobrać dane użytkownika. Przykłady są dostępne w językach C# i TypeScript.

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

Tę samą logikę można zaimplementować w języku TypeScript w następujący sposób:

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

Krok 4. Usuwanie zależności Microsoft.Identity.Web

Po zakończeniu poprzednich kroków możesz uporządkować aplikację, usuwając pakiety NuGet używane przez microsoft.Identity.Web z projektu:

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

Jeśli nadal chcesz zweryfikować tokeny w aplikacji, nie musisz w pełni usuwać oryginalnej konfiguracji uwierzytelniania, chociaż można delegować walidację całkowicie do zestawu Microsoft Entra SDK for AgentID.

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

Krok 5. Testowanie i weryfikowanie

1. Testy jednostkowe: aktualizowanie testów w celu pozorowania wywołań HTTP do zestawu SDK
2. Testy integracyjne: testowanie komunikacji SDK w środowisku staging
3. Testy wydajnościowe: mierzenie wpływu na obciążenie HTTP
4. Testy zabezpieczeń: weryfikowanie obsługi tokenów i zasad sieci

Zagadnienia dotyczące wydajności

Obciążenie zestawu SDK

Zestaw Microsoft Entra SDK for AgentID wprowadza obciążenie komunikacji HTTP:

wydajność In-Process

Użycie biblioteki Microsoft.Identity.Web ma minimalne obciążenie, ponieważ działa w ramach tego samego procesu co aplikacja, zapewniając natywne wywołania metod z mikrosekundowymi opóźnieniami i pamięcią współużytkowanego procesu bez ograniczeń protokołu HTTP. Gdy wydajność jest krytyczna, integracja w procesie jest optymalnym wyborem, ale elastyczność i niezależność od języka projektu zestawu Microsoft Entra SDK dla AgentID może przewyższać kompromisy wydajności w wielu scenariuszach.

Poniżej przedstawiono porównania wydajności i kosztów użycia metodą in-process oraz Microsoft Entra SDK dla AgentID w trybie Out-of-Process.

Zagadnienia dotyczące kosztów

Przykład kosztów

W przypadku 10 replik z konfiguracją zestawu SDK 128Mi/100m:

Pomoc techniczna i konserwacja

Podejście hybrydowe

Oba podejścia można połączyć w ramach tej samej architektury: użyj biblioteki Microsoft.Identity.Web dla usług .NET, które wymagają maksymalnej wydajności, a jednocześnie korzystając z zestawu Microsoft Entra SDK dla identyfikatora AgentID dla usług non-.NET lub gdy potrzebujesz wzorców uwierzytelniania niezależnego od języka. Ta strategia hybrydowa umożliwia optymalizowanie wydajności, gdy krytyczne jest zachowanie spójności i elastyczności w całym ekosystemie usług.

Przykładowa architektura wygląda następująco:

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

Dalsze kroki

• Przewodnik instalacji — wdrażanie zestawu Microsoft Entra SDK dla identyfikatora agenta
• Dokumentacja konfiguracji — konfigurowanie zestawu SDK
• Scenariusze — przykłady praktyczne
• Dokumentacja Microsoft.Identity.Web — informacje o bibliotece procesów