Porównanie: zestaw SDK do uwierzytelniania Microsoft Entra ID (sidecar) w porównaniu z wewnątrzprocesowym Microsoft.Identity.Web

Ten przewodnik pomaga zrozumieć różnice między pakietem Microsoft Entra ID Auth SDK (sidecar) a biblioteką Microsoft.Identity.Web działającą w procesie, służącymi do obsługi uwierzytelniania w aplikacjach. Microsoft. Biblioteka Identity.Web integruje się bezpośrednio z aplikacjami .NET w celu uzyskania maksymalnej wydajności. Zestaw SDK uwierzytelniania Microsoft Entra ID (sidecar) działa jako oddzielny kontener i obsługuje każdy język programowania za pośrednictwem interfejsów API HTTP. Wybór prawidłowego 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 procesie aplikacji. Zestaw SDK uwierzytelniania Microsoft Entra ID (sidecar) działa jako niezależna usługa obok Twojej aplikacji. Ten wybór architektury ma wpływ na czynniki, takie jak przepływ pracy programowania i złożoność operacyjna.

Microsoft. Identity.Web (proces)

Ten fragment kodu pokazuje, jak Microsoft.Identity.Web integruje się bezpośrednio z aplikacją 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 SDK do uwierzytelniania Microsoft Entra ID (sidecar) (poza procesem)

Ten fragment kodu pokazuje, jak wywołać SDK uwierzytelniania Microsoft Entra ID (sidecar) z aplikacji Node.js za pomocą 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

To, czy wybrać Microsoft.Identity.Web, czy Microsoft Entra ID Auth SDK (sidecar), zależy od wymagań aplikacji, jej architektury i strategii wdrażania. W zależności od potrzeb jedno podejście może być bardziej odpowiednie niż inne. 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 ID Auth SDK (sidecar)

W niektórych scenariuszach możesz chcieć zmigrować istniejącą aplikację platformy .NET, która korzysta z Microsoft.Identity.Web, tak aby używała pakietu Microsoft Entra ID Auth SDK (sidecar) 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 wprowadzeniem tej zmiany 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 dodaj kontener SDK do zasobnika:

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

# After: App + Microsoft Entra ID Auth SDK (sidecar)
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 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 biblioteki Microsoft.Identity.Web i zastąp je wywołaniami HTTP do punktów końcowych zestawu SDK uwierzytelniania Microsoft Entra ID (sidecar):

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 widać wywołania zestawu SDK uwierzytelniania Microsoft Entra ID (sidecar) z użyciem punktu końcowego /DownstreamApi w celu pobrania danych 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: Usuń zależności Microsoft.Identity.Web

Po wykonaniu poprzednich kroków należy uporządkować aplikację, usuwając pakiety NuGet dla 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 usuwać oryginalnej konfiguracji uwierzytelniania. Zamiast tego można delegować walidację całkowicie do zestawu SDK uwierzytelniania Microsoft Entra ID (przyczepki).

// 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 przejściowym.
3. Testy wydajnościowe: Mierzenie wpływu na obciążenie HTTP.
4. Testy zabezpieczeń: Weryfikowanie obsługi tokenów i zasad sieciowych.

Zagadnienia dotyczące wydajności

Obciążenie związane z zestawem SDK

Zestaw MICROSOFT ENTRA ID Auth SDK (sidecar) wprowadza obciążenie komunikacji HTTP:

wydajność In-Process

Korzystanie z Microsoft.Identity.Web ma minimalne zużycie zasobów, ponieważ działa w ramach tego samego procesu co aplikacja. Zapewnia ona natywne wywołania metod z opóźnieniem rzędu mikrosekund i współdzieloną pamięcią procesu bez ograniczeń protokołu HTTP. Gdy wydajność jest krytyczna, integracja procesów jest optymalnym wyborem. Jednak elastyczność pakietu Microsoft Entra ID Auth SDK (sidecar) oraz jego konstrukcja niezależna od języka mogą w wielu scenariuszach przeważać nad kompromisami dotyczącymi wydajności.

W poniższej tabeli przedstawiono porównania wydajności i kosztów dla użycia w ramach procesu oraz korzystania z zestawu SDK uwierzytelniania Microsoft Entra ID (sidecar) poza procesem:

Zagadnienia dotyczące kosztów

Przykład kosztów

W przypadku 10 replik z konfiguracją zestawu SDK o pojemności 128 miB/100 m:

Pomoc techniczna i konserwacja

Podejście hybrydowe

Oba podejścia można połączyć w ramach tej samej architektury. Użyj Microsoft.Identity.Web dla usług .NET, które wymagają maksymalnej wydajności, i użyj zestawu Microsoft Entra ID Auth SDK (w modelu sidecar) dla usług innych niż .NET lub wtedy, gdy potrzebujesz wzorców uwierzytelniania niezależnych od języka. Ta strategia hybrydowa pomaga zoptymalizować wydajność, w której ma kluczowe znaczenie, zachowując spójność i elastyczność w całym ekosystemie usług.

Przykładowa architektura jest następująca:

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 ID Auth SDK (sidecar)</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

Treści powiązane

• Przewodnik instalacji
• Dokumentacja konfiguracji
• Wywołaj podrzędne API
• Przegląd