Comparación: Microsoft Entra SDK para AgentID frente a In-Process Microsoft.Identity.Web

Esta guía le ayuda a identificar las diferencias entre el SDK de Microsoft Entra para AgentID y la biblioteca Microsoft.Identity.Web en proceso para controlar la autenticación en las aplicaciones. La biblioteca Microsoft.Identity.Web se integra directamente en aplicaciones .NET para obtener el máximo rendimiento, mientras que el SDK de Microsoft Entra para AgentID se ejecuta como un contenedor independiente y admite cualquier lenguaje de programación a través de LAS API HTTP y elegir el enfoque correcto depende de la arquitectura, el lenguaje y el entorno de implementación de la aplicación.

Diferencias arquitectónicas

La diferencia fundamental radica en dónde se ejecuta la lógica de autenticación. Microsoft.Identity.Web se ejecuta dentro del proceso de aplicación, mientras que el SDK de Microsoft Entra para AgentID funciona como un servicio independiente junto con la aplicación. Esta elección arquitectónica afecta a factores como el flujo de trabajo de desarrollo y la complejidad operativa.

Microsoft.Identity.Web (In-Process)

Este fragmento de código muestra cómo microsoft.Identity.Web se integra directamente en una aplicación 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);
    }
}

SDK de Microsoft Entra para AgentID (fuera de proceso)

Este fragmento de código muestra cómo llamar al SDK de Microsoft Entra para AgentID desde una aplicación de Node.js mediante HTTP. La llamada al punto de conexión del SDK maneja la obtención de /DownstreamApi tokens y las llamadas a la API de downstream, incluida la transferencia del token entrante para los flujos de OBO en el 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);
}

Comparación de características

Cuándo usar cada enfoque

Decidir entre Microsoft.Identity.Web y el SDK de Microsoft Entra para AgentID depende de los requisitos, la arquitectura y la estrategia de implementación de la aplicación. Dependiendo de sus necesidades, un enfoque puede ser más adecuado que el otro, y las siguientes directrices podrían ayudarle a tomar una decisión informada.

Guía de migración

Migración de Microsoft.Identity.Web al SDK de Microsoft Entra para AgentID

En determinados escenarios, es posible que quiera migrar una aplicación .NET existente mediante Microsoft.Identity.Web para aprovechar microsoft Entra SDK para AgentID para la autenticación. Las razones para la migración podrían incluir la adopción de una arquitectura de varios lenguajes, la estandarización de la autenticación entre servicios o el traslado a un modelo de implementación en contenedor.

Es necesario tener en cuenta y planear cuidadosamente antes de hacerlo. En esta sección se proporciona una ruta de migración de alto nivel con ejemplos de código que le ayudarán a realizar la transición de la aplicación.

Paso 1: Implementación del contenedor del SDK

En primer lugar, deberá agregar el contenedor del 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"

Paso 2: Migración de la configuración

A continuación, deberá transferir su configuración de appsettings.json a variables de entorno.

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

Después (Kubernetes ConfigMap/Variables de entorno)

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"

Paso 3: Actualizar código de aplicación

Busque todas las instancias de llamadas en proceso a Microsoft.Identity.Web y reemplácelas por llamadas HTTP al SDK de Microsoft Entra para puntos de conexión AgentID:

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

Después (Cualquier lenguaje con el cliente HTTP):

En el fragmento de código siguiente, podemos ver llamadas al SDK de Microsoft Entra para AgentID mediante el /DownstreamApi punto de conexión para obtener datos de usuario. Se proporcionan ejemplos en C# y 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 misma lógica se puede implementar en TypeScript de la siguiente manera:

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

Paso 4: Eliminación de dependencias Microsoft.Identity.Web

Una vez completados los pasos anteriores, puede ordenar la aplicación quitando los paquetes NuGet usados por Microsoft.Identity.Web del proyecto:

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

Si aún quiere validar tokens en la aplicación, no es necesario quitar completamente la configuración de autenticación original, aunque podría delegar la validación por completo en el SDK de Microsoft Entra para AgentID.

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

Paso 5: Probar y validar

1. Pruebas unitarias: actualización de pruebas para simular llamadas HTTP al SDK
2. Pruebas de integración: prueba de la comunicación del SDK en el almacenamiento provisional
3. Pruebas de rendimiento: medir el impacto de la sobrecarga HTTP
4. Pruebas de seguridad: validar el control de tokens y las directivas de red

Consideraciones de rendimiento

Sobrecarga del SDK

El SDK de Microsoft Entra para AgentID presenta una sobrecarga de comunicación HTTP:

rendimiento de In-Process

El uso de Microsoft.Identity.Web tiene una sobrecarga mínima, ya que se ejecuta dentro del mismo proceso que la aplicación, lo que proporciona llamadas de método nativas con latencia microsegunda y memoria de proceso compartida sin limitaciones HTTP. Cuando el rendimiento es crítico, la integración en proceso es la opción óptima, pero el SDK de Microsoft Entra para el diseño independiente del lenguaje y la flexibilidad de AgentID pueden superar las ventajas del rendimiento en muchos escenarios.

A continuación se muestran algunas comparaciones de rendimiento y costos para el uso en proceso y el uso de Microsoft Entra SDK para AgentID (fuera de proceso):

Consideraciones sobre costos

Ejemplo de costo

Para 10 réplicas con configuración del SDK de 128Mi/100m:

Soporte técnico y mantenimiento

Enfoque híbrido

Puede combinar ambos enfoques dentro de la misma arquitectura: use Microsoft.Identity.Web para servicios .NET que requieren un rendimiento máximo, al tiempo que aprovecha el SDK de Microsoft Entra para AgentID para non-.NET servicios o cuando se necesitan patrones de autenticación independientes del lenguaje. Esta estrategia híbrida le permite optimizar el rendimiento cuando es fundamental al tiempo que mantiene la coherencia y la flexibilidad en todo el ecosistema de servicios.

Una arquitectura de ejemplo sería la siguiente:

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

Pasos siguientes

• Guía de instalación : Implementación del SDK de Microsoft Entra para AgentID
• Referencia de configuración : configuración del SDK
• Escenarios : ejemplos prácticos
• Documentación de Microsoft.Identity.Web : información sobre la biblioteca en proceso