Vergleich: Microsoft Entra SDK für AgentID vs. In-Process Microsoft.Identity.Web

Dieses Handbuch hilft Ihnen, die Unterschiede zwischen dem Microsoft Entra SDK für AgentID und der in-process Microsoft.Identity.Web Library zur Behandlung der Authentifizierung in Ihren Anwendungen zu ermitteln. Die Microsoft.Identity.Web-Bibliothek integriert sich direkt in .NET-Anwendungen für maximale Leistung, während das Microsoft Entra SDK für AgentID als separater Container ausgeführt wird und jede Programmiersprache über HTTP-APIs unterstützt und die Auswahl des richtigen Ansatzes von der Architektur, Sprache und Bereitstellungsumgebung Ihrer Anwendung abhängt.

Architekturunterschiede

Der grundlegende Unterschied liegt darin , wo die Authentifizierungslogik ausgeführt wird. Microsoft.Identity.Web wird innerhalb Ihres Anwendungsprozesses ausgeführt, während das Microsoft Entra SDK für AgentID zusammen mit Ihrer Anwendung als unabhängiger Dienst fungiert. Diese Architekturauswahl wirkt sich auf Faktoren wie Entwicklungsworkflow und betriebstechnische Komplexität aus.

Microsoft.Identity.Web (In-Process)

Dieser Codeausschnitt zeigt, wie Microsoft.Identity.Web direkt in eine ASP.NET Core-Anwendung integriert wird:

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

Microsoft Entra SDK für AgentID (Außerhalb des Prozesses)

Dieser Codeausschnitt veranschaulicht, wie Sie das Microsoft Entra SDK für AgentID aus einer Node.js Anwendung mit HTTP aufrufen. Der Aufruf des /DownstreamApi Endpunkts des SDK übernimmt die Verarbeitung der Tokenakquisition und der aufeinanderfolgenden API-Aufrufe. Hierbei wird das eingehende Token für OBO-Flows im Authorization Header übergeben.

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

Feature-Vergleich

Wann jeder Ansatz verwendet werden soll

Die Entscheidung zwischen Microsoft.Identity.Web und dem Microsoft Entra SDK für AgentID hängt von den Anforderungen, der Architektur und der Bereitstellungsstrategie Ihrer Anwendung ab. Je nach Ihren Anforderungen kann ein Ansatz besser geeignet sein als der andere, und die folgenden Richtlinien können Ihnen helfen, eine fundierte Entscheidung zu treffen.

Migrationsleitfaden

Migrieren von Microsoft.Identity.Web zu Microsoft Entra SDK für AgentID

In bestimmten Szenarien möchten Sie möglicherweise eine vorhandene .NET-Anwendung mithilfe von Microsoft.Identity.Web migrieren, um das Microsoft Entra SDK für AgentID für die Authentifizierung zu nutzen. Die Gründe für die Migration könnten die Einführung einer mehrsprachigen Architektur, die Standardisierung der Authentifizierung über Dienste hinweg oder das Verschieben in ein containerisiertes Bereitstellungsmodell umfassen.

Es ist eine sorgfältige Prüfung und Planung erforderlich, bevor Sie dies tun. Dieser Abschnitt enthält einen allgemeinen Migrationspfad mit Codebeispielen, die Ihnen beim Übergang Ihrer Anwendung helfen.

Schritt 1: Bereitstellen des SDK-Containers

Zuerst müssen Sie den SDK-Container zu Ihrem Pod hinzufügen:

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

Schritt 2: Migrieren der Konfiguration

Als nächstes müssen Sie Ihre Konfiguration von appsettings.json auf Umgebungsvariablen übertragen.

Vorher (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"
    }
  }
}

After (Kubernetes ConfigMap / Umgebungsvariablen)

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"

Schritt 3: Aktualisieren des Anwendungscodes

Suchen Sie alle Instanzen von interprozessualen Aufrufen an Microsoft.Identity.Web, und ersetzen Sie sie durch HTTP-Aufrufe an das Microsoft Entra SDK für AgentID-Endpunkte.

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

After (Any language with HTTP client):

Im folgenden Codeausschnitt werden Aufrufe des Microsoft Entra SDK für AgentID mithilfe des /DownstreamApi Endpunkts zum Abrufen von Benutzerdaten angezeigt. Beispiele werden in C# und TypeScript bereitgestellt.

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

Dieselbe Logik kann in TypeScript wie folgt implementiert werden:

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

Schritt 4: Entfernen von Microsoft.Identity.Web-Abhängigkeiten

Nachdem die vorherigen Schritte abgeschlossen wurden, können Sie Ihre Anwendung beräuigen, indem Sie die nuGet-Pakete entfernen, die von Microsoft.Identity.Web aus Ihrem Projekt verwendet werden:

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

Wenn Sie weiterhin Token in Ihrer App überprüfen möchten, müssen Sie die ursprüngliche Authentifizierungskonfiguration nicht vollständig entfernen, obwohl Sie die Validierung vollständig an das Microsoft Entra SDK für AgentID delegieren können.

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

Schritt 5: Testen und Überprüfen

1. Komponententests: Aktualisieren von Tests zum Modellieren von HTTP-Aufrufen des SDK
2. Integrationstests: Testen der SDK-Kommunikation in Staging
3. Leistungstests: Messen des HTTP-Overheadeffekts
4. Sicherheitstests: Überprüfen der Tokenbehandlung und Netzwerkrichtlinien

Überlegungen zur Leistung

SDK-Aufwand

Das Microsoft Entra SDK für AgentID führt den HTTP-Kommunikationsaufwand ein:

In-Process Leistung

Die Verwendung von Microsoft.Identity.Web hat minimalen Aufwand, da er innerhalb desselben Prozesses wie Ihre Anwendung ausgeführt wird, und stellt systemeigene Methodenaufrufe mit Mikrosekundenlatenz und freigegebenem Prozessspeicher ohne HTTP-Einschränkungen bereit. Wenn Leistung entscheidend ist, ist die In-Process-Integration die optimale Wahl, aber das Microsoft Entra SDK für AgentIDs Flexibilität und sprachunabhängiges Design kann in vielen Szenarien die Leistungseinbußen überwiegen.

Im Folgenden finden Sie einige Leistungs- und Kostenvergleiche für die In-Process-Nutzung und das Microsoft Entra SDK für die Verwendung von AgentID (Out-of-Process):

Kostenüberlegungen

Kostenbeispiel

Für 10 Replikate mit 128Mi/100m SDK-Konfiguration:

Support und Wartung

Hybridansatz

Sie können beide Ansätze innerhalb derselben Architektur kombinieren: Verwenden Sie Microsoft.Identity.Web für .NET-Dienste, die eine maximale Leistung erfordern, während Sie das Microsoft Entra SDK für AgentID für non-.NET-Dienste nutzen oder sprachunabhängige Authentifizierungsmuster benötigen. Diese Hybridstrategie ermöglicht es Ihnen, die Leistung zu optimieren, wobei Konsistenz und Flexibilität im gesamten Dienstökosystem von entscheidender Bedeutung bleiben.

Eine Beispielarchitektur wäre wie folgt:

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

Nächste Schritte

• Installationshandbuch – Bereitstellen des Microsoft Entra SDK für AgentID
• Konfigurationsreferenz – Konfigurieren des SDK
• Szenarien – Praktische Beispiele
• Microsoft.Identity.Web Documentation – Informationen zur In-Process-Bibliothek