Confronto: Microsoft Entra SDK per AgentID contro In-Process Microsoft.Identity.Web

Questa guida consente di identificare le differenze tra Microsoft Entra SDK per AgentID e la libreria Microsoft.Identity.Web in-process per la gestione dell'autenticazione nelle applicazioni. La libreria Microsoft.Identity.Web si integra direttamente nelle applicazioni .NET per ottenere prestazioni massime, mentre Microsoft Entra SDK per AgentID viene eseguito come contenitore separato e supporta qualsiasi linguaggio di programmazione tramite API HTTP e 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, mentre Microsoft Entra SDK per AgentID opera 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 AgentID (fuori dal processo)

Questo frammento di codice illustra come chiamare Microsoft Entra SDK per AgentID da un'applicazione Node.js tramite 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 tra funzionalità

Quando usare ogni approccio

La scelta tra Microsoft.Identity.Web e Microsoft Entra SDK per AgentID dipende dai requisiti, dall'architettura e dalla strategia di distribuzione dell'applicazione. A seconda delle esigenze, un approccio può essere più adatto rispetto all'altro e le linee guida seguenti possono aiutare a prendere una decisione informata.

Linee guida per la migrazione

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

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

Prima di eseguire questa operazione, è necessaria un'attenta 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

Prima di tutto, è necessario aggiungere 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

Successivamente, sarà necessario trasferire 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

Individua tutte le istanze delle chiamate in-process a Microsoft.Identity.Web e sostituiscile con chiamate HTTP agli endpoint dell'SDK di Microsoft Entra per AgentID.

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 è possibile visualizzare le chiamate a Microsoft Entra SDK per AgentID 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

La stessa logica può essere implementata in TypeScript come segue:

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 Microsoft.Identity.Web

Dopo aver completato i passaggi precedenti, è possibile riordinare l'applicazione rimuovendo i pacchetti NuGet usati da 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 vuoi ancora convalidare i token nell'app, non devi rimuovere completamente la configurazione di autenticazione originale, anche se puoi delegare completamente la convalida a Microsoft Entra SDK 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: Testare la comunicazione 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

Overhead dell'SDK

Microsoft Entra SDK per AgentID introduce un sovraccarico di comunicazione HTTP:

prestazioni durante il processo

L'uso di Microsoft.Identity.Web ha un sovraccarico minimo perché viene eseguito nello stesso processo dell'applicazione, fornendo chiamate di metodi nativi con latenza microseconda e memoria del processo condiviso senza limitazioni HTTP. Quando le prestazioni sono critiche, l'integrazione in-process è la scelta ottimale, ma la flessibilità e la progettazione indipendente dal linguaggio di Microsoft Entra SDK per AgentID possono superare i compromessi delle prestazioni in molti scenari.

Di seguito sono riportati alcuni confronti tra prestazioni e costi per l'utilizzo in-process e l'utilizzo di Microsoft Entra SDK per AgentID (Out-of-Process):

Considerazioni sul costo

Esempio di costo

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

Supporto e manutenzione

Approccio ibrido

È possibile combinare entrambi gli approcci all'interno della stessa architettura: usare Microsoft.Identity.Web per i servizi .NET che richiedono prestazioni massime, sfruttando microsoft Entra SDK per AgentID 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

Passaggi successivi

• Guida all'installazione - Distribuire Microsoft Entra SDK per AgentID
• Informazioni di riferimento sulla configurazione - Configurare l'SDK
• Scenari - Esempi pratici
• Documentazione di Microsoft.Identity.Web - Informazioni sulla libreria in-process