Vergelijking: Microsoft Entra SDK voor agent-id versus In-Process Microsoft. Identity.Web

Deze handleiding helpt u bij het identificeren van de verschillen tussen de Microsoft Entra SDK voor agent-id en de in-process Microsoft. Identity.Web library voor het afhandelen van verificatie in uw toepassingen. De Microsoft. Identity.Web library kan rechtstreeks worden geïntegreerd in .NET toepassingen voor maximale prestaties. De Microsoft Entra SDK voor agent-id wordt uitgevoerd als een afzonderlijke container en ondersteunt elke programmeertaal via HTTP-API's. Het kiezen van de juiste benadering is afhankelijk van de architectuur, taal en implementatieomgeving van uw toepassing.

Verschillen in architectuur

Het fundamentele verschil ligt in waar verificatielogica wordt uitgevoerd. Microsoft. Identity.Web wordt uitgevoerd binnen uw toepassingsproces. De Microsoft Entra SDK voor agent-id fungeert als een onafhankelijke service naast uw toepassing. Deze architectuurkeuze heeft invloed op factoren zoals ontwikkelingswerkstroom en operationele complexiteit.

Microsoft.Identity.Web (in-process)

Dit codefragment laat zien hoe Microsoft. Identity.Web kan rechtstreeks worden geïntegreerd in een ASP.NET Core-toepassing:

// 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 voor Agent ID (Out-of-Process)

Dit codefragment laat zien hoe u de Microsoft Entra SDK voor agent-id aanroept vanuit een Node.js-toepassing met behulp van HTTP. De aanroep naar het /DownstreamApi-eindpunt van de SDK verwerkt tokenverwerving en downstream API-aanroepen, inclusief het doorgeven van het binnenkomende token voor OBO-stromen in de Authorization header.

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

Vergelijking van functies

Wanneer moet u elke benadering gebruiken

Kiezen tussen Microsoft. Identity.Web en de Microsoft Entra SDK voor agent-id zijn afhankelijk van de vereisten, architectuur en implementatiestrategie van uw toepassing. Afhankelijk van uw behoeften kan één benadering geschikter zijn dan de andere. De volgende richtlijnen kunnen u helpen bij het nemen van een weloverwogen beslissing.

Migratierichtlijnen

Migreren van Microsoft.Identity.Web naar Microsoft Entra SDK for AgentID

In bepaalde scenario's wilt u mogelijk een bestaande .NET-toepassing migreren die gebruikmaakt van Microsoft. Identity.Web om gebruik te maken van de Microsoft Entra SDK voor agent-id voor verificatie. Redenen voor migratie kunnen bestaan uit het aannemen van een architectuur met meerdere talen, het standaardiseren van verificatie tussen services of het overstappen op een containerimplementatiemodel.

Zorgvuldige overwegingen en planning zijn vereist voordat u deze wijziging aanbrengt. Deze sectie bevat een migratiepad op hoog niveau met codevoorbeelden waarmee u uw toepassing kunt overstappen.

Stap 1: SDK-container implementeren

Voeg eerst de SDK-container toe aan uw pod:

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

Stap 2: Configuratie migreren

Breng vervolgens uw configuratie over van appsettings.json naar omgevingsvariabelen:

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

Na (Kubernetes ConfigMap en omgevingsvariabelen)

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"

Stap 3: toepassingscode bijwerken

Zoek alle exemplaren van in-process aanroepen naar Microsoft.Identity.Web en vervang deze door HTTP-aanroepen naar de Microsoft Entra SDK voor Agent-ID-eindpunten.

Voor (C# met 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);
    }
}

Na (elke taal met HTTP-client):

In het volgende codefragment ziet u aanroepen naar de Microsoft Entra SDK voor agent-id met behulp van het /DownstreamApi-eindpunt om gebruikersgegevens op te halen. Voorbeelden worden gegeven in C# en 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

U kunt dezelfde logica in TypeScript als volgt implementeren:

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

Stap 4: verwijder Microsoft. Identity.Web-afhankelijkheden

Nadat u de vorige stappen hebt voltooid, moet u uw toepassing opgeruimd maken door de NuGet-pakketten voor Microsoft te verwijderen. Identity.Web vanuit uw project:

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

Als u nog steeds tokens in uw app wilt valideren, hoeft u de oorspronkelijke verificatieconfiguratie niet te verwijderen. In plaats daarvan kunt u validatie volledig delegeren aan de Microsoft Entra SDK voor AgentID.

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

Stap 5: Testen en valideren

1. Eenheidstests: Werk tests bij om HTTP-aanroepen naar de SDK te mocken.
2. Integratietests: Test SDK-communicatie in de staging-omgeving.
3. Prestatietests: De impact van HTTP-overhead meten.
4. Beveiligingstests: tokenafhandeling en netwerkbeleid valideren.

Prestatie-overwegingen

SDK overhead

De Microsoft Entra SDK voor agent-id introduceert overhead voor HTTP-communicatie:

In-procesprestaties

Met Microsoft.Identity.Web heeft u minimale overhead omdat deze binnen hetzelfde proces als uw toepassing wordt uitgevoerd. Het biedt systeemeigen methodeaanroepen met microsecondenlatentie en gedeeld procesgeheugen zonder HTTP-beperkingen. Wanneer de prestaties essentieel zijn, is integratie in proces de optimale keuze. De Microsoft Entra SDK voor het flexibiliteits- en taalagnostische ontwerp van AgentID kan echter in veel scenario's opwegen tegen de prestaties.

In de volgende tabel worden enkele prestatie- en kostenvergelijkingen weergegeven voor gebruik in proces en Microsoft Entra SDK voor gebruik van agent-id's (out-of-process):

Kostenoverwegingen

Voorbeeld van kosten

Voor 10 replica's met 128 MiB/100m SDK-configuratie:

Ondersteuning en onderhoud

Hybride benadering

U kunt beide benaderingen in dezelfde architectuur combineren. Gebruik Microsoft. Identity.Web voor .NET-services waarvoor maximale prestaties zijn vereist, en gebruik de Microsoft Entra SDK voor agent-id voor niet-.NET-services of wanneer u taalagnostische verificatiepatronen nodig hebt. Met deze hybride strategie kunt u de prestaties optimaliseren waarbij het essentieel is, terwijl consistentie en flexibiliteit in uw hele service-ecosysteem behouden blijft.

Een voorbeeldarchitectuur is als volgt:

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

Verwante inhoud

• Installatiehandleiding
• Configuratiereferentie
• Downstream-API aanroepen
• Overzicht