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

Esta guía le ayuda a identificar las diferencias entre el SDK de Microsoft Entra para Agent ID y la biblioteca de Microsoft.Identity.Web en proceso para controlar la autenticación en sus aplicaciones. La biblioteca Microsoft.Identity.Web se integra directamente en las aplicaciones de .NET para lograr el máximo rendimiento. El SDK de Microsoft Entra para el identificador del agente se ejecuta como un contenedor independiente y admite cualquier lenguaje de programación a través de las API HTTP. 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. El SDK de Microsoft Entra para la Identificación de Agente opera como un servicio independiente junto a tu aplicación. Esta elección arquitectónica afecta a factores como el flujo de trabajo de desarrollo y la complejidad operativa.

Microsoft.Identity.Web (en proceso)

Este fragmento de código muestra cómo Microsoft. Identity.Web se integra directamente en una aplicación de 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 ID de agente (fuera de proceso)

Este fragmento de código muestra cómo llamar al SDK de Microsoft Entra para el identificador del agente 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 el ID de agente depende de los requisitos, la arquitectura y la estrategia de implementación de la aplicación. Dependiendo de sus necesidades, un enfoque podría ser más adecuado que el otro. Las siguientes instrucciones pueden ayudarle a tomar una decisión informada.

Guía de migración

Migración desde Microsoft. Identity.Web para Microsoft Entra SDK para AgentID

En determinados escenarios, es posible que desee migrar una aplicación de .NET existente que use Microsoft. Identity.Web para aprovechar el SDK de Microsoft Entra para el identificador del agente para la autenticación. Los motivos de 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 contenedores.

Es necesario tener en cuenta y planear cuidadosamente antes de realizar este cambio. 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, agregue 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, transfiera la configuración de appsettings.json a variables de entorno.

Antes de (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: Actualización del código de la 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 de ID de agente.

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, puede ver llamadas al SDK de Microsoft Entra para el ID del agente usando el punto de conexión de /DownstreamApi 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

Puede implementar la misma lógica 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: Eliminar dependencias de Microsoft.Identity.Web

Después de completar los pasos anteriores, ordene la aplicación quitando los paquetes NuGet para Microsoft. Identity.Web desde el 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 la configuración de autenticación original. En su lugar, puede 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: actualice las pruebas para simular llamadas HTTP al SDK.
2. Pruebas de integración: Pruebe la comunicación del SDK en el entorno de preproducción.
3. Pruebas de rendimiento: mida el impacto de la sobrecarga HTTP.
4. Pruebas de seguridad: valide el control de tokens y las directivas de red.

Consideraciones sobre el rendimiento

Sobrecarga del SDK

El SDK de Microsoft Entra para el identificador del agente 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. 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. Sin embargo, la flexibilidad y el diseño independiente del lenguaje del SDK de Microsoft Entra para AgentID pueden superar los compromisos de rendimiento en muchos escenarios.

En la tabla siguiente se muestran algunas comparaciones de rendimiento y costos para el uso en proceso y el SDK de Microsoft Entra para el uso del id. de agente (fuera del proceso):

Consideraciones sobre los costos

Ejemplo de costo

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

Soporte técnico y mantenimiento

Enfoque híbrido

Puede combinar ambos enfoques dentro de la misma arquitectura. Use Microsoft. Identity.Web para servicios de .NET que requieren un rendimiento máximo y usan el SDK de Microsoft Entra para el identificador de agente para servicios que no son de .NET o cuando se necesitan patrones de autenticación independientes del lenguaje. Esta estrategia híbrida le ayuda a optimizar el rendimiento donde es fundamental al tiempo que mantiene la coherencia y la flexibilidad en todo el ecosistema de servicios.

Una arquitectura de ejemplo es 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

Contenido relacionado

• Guía de instalación
• Referencia de configuración
• Llamar a la API descendente
• Información general