Jämförelse: Microsoft Entra SDK för agent-ID jämfört med In-Process Microsoft. Identity.Web

Den här guiden hjälper dig att identifiera skillnaderna mellan Microsoft Entra SDK för agent-ID och den pågående Microsoft. Identity.Web-bibliotek för hantering av autentisering i dina program. Microsoft. Identity.Web-biblioteket integreras direkt i .NET program för maximal prestanda. Microsoft Entra SDK för agent-ID körs som en separat container och stöder alla programmeringsspråk via HTTP-API:er. Om du väljer rätt metod beror det på programmets arkitektur, språk och distributionsmiljö.

Arkitekturskillnader

Den grundläggande skillnaden ligger i var autentiseringslogik körs. Microsoft. Identity.Web körs i din programprocess. Microsoft Entra SDK för agent-ID fungerar som en oberoende tjänst tillsammans med ditt program. Det här arkitekturvalet påverkar faktorer som utvecklingsarbetsflöde och driftskomplexitet.

Microsoft.Identity.Web (pågående)

Det här kodfragmentet visar hur Microsoft. Identity.Web integreras direkt i ett ASP.NET Core program:

// 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 agent-ID (out-of-process)

Det här kodfragmentet visar hur du anropar Microsoft Entra SDK för agent-ID från ett Node.js program med HTTP. Anropet till SDK:s /DownstreamApi-slutpunkt hanterar tokenförvärv och nedströms API-anrop, inklusive att vidarebefordra den inkommande token för OBO-flöden i Authorization huvud.

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

Jämförelse av funktioner

När du ska använda varje metod

Beslutar mellan Microsoft. Identity.Web och Microsoft Entra SDK för agent-ID beror på programmets krav, arkitektur och distributionsstrategi. Beroende på dina behov kan en metod vara lämpligare än den andra. Följande riktlinjer kan hjälpa dig att fatta ett välgrundat beslut.

Vägledning för migrering

Migrera från Microsoft. Identity.Web till Microsoft Entra SDK för AgentID

I vissa scenarier kanske du vill migrera ett befintligt .NET program som använder Microsoft. Identity.Web för att utnyttja Microsoft Entra SDK för agent-ID för autentisering. Orsaker till migreringen kan vara att införa en arkitektur med flera språk, standardisera autentisering mellan tjänster eller flytta till en containerbaserad distributionsmodell.

Noggrant övervägande och planering krävs innan du gör den här ändringen. Det här avsnittet innehåller en övergripande migreringssökväg med kodexempel som hjälper dig att överföra ditt program.

Steg 1: Distribuera SDK-container

Lägg först till SDK-containern i podden:

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

Steg 2: Migrera konfiguration

Överför sedan konfigurationen från appsettings.json till miljövariabler:

Före (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"
    }
  }
}

Efter (Kubernetes ConfigMap/Miljövariabler)

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"

Steg 3: Uppdatera programkoden

Leta upp alla instanser av pågående anrop till Microsoft. Identity.Web och ersätt dem med HTTP-anrop till Microsoft Entra SDK för agent-ID-slutpunkter:

Före (C# med 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);
    }
}

Efter (valfritt språk med HTTP-klient):

I följande kodsnutt visas anrop till Microsoft Entra SDK för att använda agent-ID med hjälp av slutpunkten /DownstreamApi för att hämta användardata. Exempel finns i C# och 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

Du kan implementera samma logik i TypeScript på följande sätt:

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

Steg 4: Ta bort Microsoft. Identity.Web-beroenden

När du har slutfört föregående steg kan du städa programmet genom att ta bort NuGet-paketen för Microsoft. Identity.Web från projektet:

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

Om du fortfarande vill verifiera token i din app behöver du inte ta bort den ursprungliga autentiseringskonfigurationen. I stället kan du delegera valideringen helt till Microsoft Entra SDK för AgentID.

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

Steg 5: Testa och verifiera

1. Enhetstester: Uppdatera tester för att simulera HTTP-anrop till SDK:t.
2. Integreringstester: Testa SDK-kommunikation i stagingmiljö.
3. Prestandatester: Mät påverkan på HTTP-omkostnader.
4. Säkerhetstester: Verifiera tokenhantering och nätverksprinciper.

Prestandaöverväganden

Omkostnader för SDK

Microsoft Entra SDK för agent-ID introducerar HTTP-kommunikationskostnader:

Processintern prestanda

Använda Microsoft. Identity.Web har minimala omkostnader eftersom det körs inom samma process som ditt program. Den tillhandahåller inbyggda metodanrop med mikrosekunders svarstid och delat processminne utan HTTP-begränsningar. När prestanda är kritiskt är processintegrering det optimala valet. Men Microsoft Entra SDK för AgentID:s flexibilitet och språkagnostiska design kan uppväga prestandavägningarna i många scenarier.

I följande tabell visas några prestanda- och kostnadsjämförelser för användning i processen och Microsoft Entra SDK för agent-ID-användning (out-of-process):

Kostnadsöverväganden

Kostnadsexempel

För 10 repliker med 128 MiB/100m SDK-konfiguration:

Support och underhåll

Hybridmetod

Du kan kombinera båda metoderna i samma arkitektur. Använd Microsoft. Identity.Web för .NET tjänster som kräver maximal prestanda och använder Microsoft Entra SDK för agent-ID för icke-.NET tjänster eller när du behöver språkagnostiska autentiseringsmönster. Den här hybridstrategin hjälper dig att optimera prestanda där den är kritisk och samtidigt upprätthålla konsekvens och flexibilitet i hela tjänstekosystemet.

Ett exempel på en arkitektur är följande:

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

Relaterat innehåll

• Installationsguide
• Konfigurationsreferens
• Anropa nedströms-API
• Översikt