Confronto: Microsoft Entra SDK per ID agente e In-Process Microsoft. Identity.Web

Questa guida consente di identificare le differenze tra l'SDK Microsoft Entra per l'ID agente e la libreria in-process Microsoft.Identity.Web per la gestione dell'autenticazione nelle applicazioni. Microsoft. La libreria Identity.Web si integra direttamente nelle applicazioni .NET per ottenere prestazioni massime. L'SDK di Microsoft Entra per l'ID agente viene eseguito come contenitore separato e supporta qualsiasi linguaggio di programmazione tramite LE API HTTP. La scelta dell'approccio corretto dipende dall'architettura, dal linguaggio e dall'ambiente di distribuzione dell'applicazione.

Differenze architetturali

La differenza fondamentale risiede nella posizione in cui viene eseguita la logica di autenticazione. Microsoft. Identity.Web viene eseguito all'interno del processo dell'applicazione. L'SDK Microsoft Entra per l'ID agente funziona come servizio indipendente insieme all'applicazione. Questa scelta dell'architettura influisce su fattori quali il flusso di lavoro di sviluppo e la complessità operativa.

Microsoft.Identity.Web (in-process)

Questo frammento di codice mostra come Microsoft. Identity.Web si integra direttamente in un'applicazione 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);
    }
}

Microsoft Entra SDK per l'ID agente (fuori dal processo)

Questo frammento di codice illustra come chiamare Microsoft Entra SDK per l'ID agente da un'applicazione Node.js usando HTTP. La chiamata all'endpoint dell'SDK /DownstreamApi gestisce l'acquisizione di token e le chiamate API downstream, incluso il passaggio del token in ingresso per i flussi OBO nell'intestazione 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);
}

Confronto delle funzionalità

Quando usare ogni approccio

Decidere tra Microsoft. Identity.Web e Microsoft Entra SDK per l'ID agente dipendono dai requisiti, dall'architettura e dalla strategia di distribuzione dell'applicazione. A seconda delle esigenze, un approccio potrebbe essere più adatto rispetto all'altro. Le linee guida seguenti consentono di prendere una decisione informata.

Indicazioni sulla migrazione

Migrazione da Microsoft. Identity.Web per Microsoft Entra SDK per AgentID

In alcuni scenari può essere necessario eseguire la migrazione di un'applicazione .NET esistente che usa Microsoft. Identity.Web per sfruttare Microsoft Entra SDK per l'ID agente per l'autenticazione. I motivi della migrazione possono includere l'adozione di un'architettura multi-linguaggio, la standardizzazione dell'autenticazione tra i servizi o il passaggio a un modello di distribuzione in contenitori.

Prima di apportare questa modifica, è necessario prestare attenzione alla valutazione e alla pianificazione. Questa sezione fornisce un percorso di migrazione di alto livello con esempi di codice che consentono di eseguire la transizione dell'applicazione.

Passaggio 1: Distribuire il contenitore SDK

Aggiungere prima di tutto il contenitore SDK al 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"

Passaggio 2: Eseguire la migrazione della configurazione

Trasferire quindi la configurazione da appsettings.json a variabili di ambiente:

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

Dopo (Kubernetes ConfigMap/Variabili di ambiente)

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"

Passaggio 3: Aggiornare il codice dell'applicazione

Individuare tutte le istanze di chiamate in-process a Microsoft.Identity.Web e sostituirle con chiamate HTTP agli endpoint Microsoft Entra SDK per l'Agent ID:

Before (C# con 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);
    }
}

Dopo (qualsiasi linguaggio con client HTTP):

Nel frammento di codice seguente vengono visualizzate chiamate all'SDK di Microsoft Entra per l'ID agente usando l'endpoint /DownstreamApi per ottenere i dati utente. Gli esempi sono disponibili in C# e 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

È possibile implementare la stessa logica in TypeScript come indicato di seguito:

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

Passaggio 4: Rimuovere le dipendenze di Microsoft.Identity.Web

Dopo aver completato i passaggi precedenti, riordinare l'applicazione rimuovendo i pacchetti NuGet per Microsoft. Identity.Web dal progetto:

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

Se si vogliono comunque convalidare i token nell'app, non è necessario rimuovere la configurazione di autenticazione originale. È invece possibile delegare interamente la convalida all'SDK di Microsoft Entra per AgentID.

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

Passaggio 5: Testare e convalidare

1. Unit test: aggiornare i test per simulare le chiamate HTTP all'SDK.
2. Test di integrazione: verificare la comunicazione dell'SDK nell'ambiente di staging.
3. Test delle prestazioni: misurare l'impatto dell'overhead HTTP.
4. Test di sicurezza: convalidare la gestione dei token e i criteri di rete.

Considerazioni sulle prestazioni

Costi generali dell'SDK

L'SDK di Microsoft Entra per l'ID agente introduce un sovraccarico di comunicazione HTTP:

Prestazioni del processo

L'utilizzo di Microsoft Identity.Web ha un sovraccarico minimo perché viene eseguito nello stesso processo dell'applicazione. Fornisce chiamate al metodo nativo con latenza microseconda e memoria del processo condiviso senza limitazioni HTTP. Quando le prestazioni sono critiche, l'integrazione in-process è la scelta ottimale. Tuttavia, l'SDK di Microsoft Entra, grazie alla sua flessibilità e al design indipendente dal linguaggio di AgentID, potrebbe superare i compromessi delle prestazioni in molti scenari.

La tabella seguente mostra alcuni confronti di prestazioni e costi per l'utilizzo in-process e per l'utilizzo dell'SDK di Microsoft Entra per l'Agente ID (fuori-processo).

Considerazioni sui costi

Esempio di costo

Per 10 repliche con configurazione 128 MiB/100m SDK:

Supporto e manutenzione

Approccio ibrido

È possibile combinare entrambi gli approcci all'interno della stessa architettura. Usare Microsoft. Identity.Web per i servizi di .NET che richiedono prestazioni massime e usano Microsoft Entra SDK per l'ID agente per i servizi non .NET o quando sono necessari modelli di autenticazione indipendenti dal linguaggio. Questa strategia ibrida consente di ottimizzare le prestazioni in cui è fondamentale mantenendo la coerenza e la flessibilità nell'intero ecosistema di servizi.

Un'architettura di esempio è la seguente:

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

Contenuti correlati

• Guida all'installazione
• Informazioni di riferimento sulla configurazione
• Chiamare l'API Downstream
• Sintesi