Comparação: SDK do Microsoft Entra para AgentID vs. In-Process Microsoft.Identity.Web

Este guia ajuda você a identificar as diferenças entre o SDK do Microsoft Entra para AgentID e a biblioteca Microsoft.Identity.Web em processo para lidar com a autenticação em seus aplicativos. A biblioteca Microsoft.Identity.Web integra-se diretamente a aplicativos .NET para obter o máximo de desempenho, enquanto o SDK do Microsoft Entra para AgentID é executado como um contêiner separado e dá suporte a qualquer linguagem de programação por meio de APIs HTTP e escolher a abordagem correta depende da arquitetura, linguagem e ambiente de implantação do aplicativo.

Diferenças de arquitetura

A diferença fundamental está no local em que a lógica de autenticação é executada. Microsoft.Identity.Web é executado em seu processo de aplicativo, enquanto o SDK do Microsoft Entra para AgentID opera como um serviço independente junto com seu aplicativo. Essa escolha arquitetônica afeta fatores como fluxo de trabalho de desenvolvimento e complexidade operacional.

Microsoft.Identity.Web (In-Process)

Este snippet de código mostra como o Microsoft.Identity.Web se integra diretamente a um aplicativo 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 do Microsoft Entra para AgentID (fora de processo)

Este snippet de código demonstra como chamar o SDK do Microsoft Entra para AgentID de um aplicativo Node.js usando HTTP. A chamada para o ponto de extremidade do SDK manipula a aquisição de token /DownstreamApi e realiza chamadas à API subsequente, incluindo a transmissão do token de entrada para fluxos OBO no cabeçalho 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);
}

Comparação de Funcionalidades

Quando usar cada abordagem

Decidir entre o Microsoft.Identity.Web e o SDK do Microsoft Entra para AgentID depende dos requisitos, da arquitetura e da estratégia de implantação do aplicativo. Dependendo de suas necessidades, uma abordagem pode ser mais adequada do que a outra e as diretrizes a seguir podem ajudá-lo a tomar uma decisão informada.

Diretrizes de migração

Migrando do Microsoft.Identity.Web para o SDK do Microsoft Entra para AgentID

Em determinados cenários, talvez você queira migrar um aplicativo .NET existente usando Microsoft.Identity.Web para aproveitar o SDK do Microsoft Entra para AgentID para autenticação. Os motivos para a migração podem incluir a adoção de uma arquitetura de vários idiomas, a padronização da autenticação entre serviços ou a mudança para um modelo de implantação em contêineres.

Consideração e planejamento cuidadosos são necessários antes de você fazer isso. Esta seção fornece um caminho de migração de alto nível com exemplos de código para ajudá-lo a fazer a transição do aplicativo.

Etapa 1: Implantar contêiner do SDK

Primeiro, você precisará adicionar o contêiner do SDK ao 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"

Etapa 2: Migrar a configuração

Em seguida, você precisará transferir sua configuração de appsettings.json para variáveis de ambiente.

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

After (Kubernetes ConfigMap/Environment Variables)

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"

Etapa 3: Atualizar código do aplicativo

Localize todas as instâncias de chamadas internas para Microsoft.Identity.Web e substitua-as por chamadas HTTP para o SDK do Microsoft Entra nos endpoints do AgentID.

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

Depois (qualquer idioma com cliente HTTP):

No snippet a seguir, podemos ver chamadas para o Microsoft Entra SDK utilizando o endpoint /DownstreamApi do AgentID para obter dados do usuário. Exemplos são fornecidos em 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

A mesma lógica pode ser implementada no TypeScript da seguinte maneira:

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

Etapa 4: Remover dependências microsoft.Identity.Web

Depois que as etapas anteriores tiverem sido concluídas, você poderá arrumar seu aplicativo removendo os pacotes NuGet usados pelo Microsoft.Identity.Web do seu projeto:

<!-- 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 você ainda quiser validar tokens em seu aplicativo, não precisará remover totalmente a configuração de autenticação original, embora possa delegar a validação inteiramente ao SDK do Microsoft Entra para AgentID.

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

Etapa 5: Testar e validar

1. Testes de unidade: atualizar testes para simular chamadas HTTP para o SDK
2. Testes de integração: Testar a comunicação do SDK no ambiente de testes
3. Testes de desempenho: medir o impacto de sobrecarga HTTP
4. Testes de segurança: validar o tratamento de tokens e as políticas de rede

Considerações sobre desempenho

A sobrecarga do SDK

O SDK do Microsoft Entra para AgentID apresenta a sobrecarga de comunicação HTTP:

Desempenho do In-Process

O uso do Microsoft.Identity.Web tem sobrecarga mínima, pois é executado no mesmo processo que seu aplicativo, fornecendo chamadas de método nativo com latência de microssegundos e memória de processo compartilhado sem limitações HTTP. Quando o desempenho é crítico, a integração em processo é a opção ideal, mas a flexibilidade e o design independente de linguagem do SDK do Microsoft Entra para o AgentID podem superar os compromissos de desempenho em muitos cenários.

Veja a seguir algumas comparações de desempenho e custo para uso em processo e uso do SDK do Microsoft Entra para AgentID (fora do processo):

Considerações de custo

Exemplo de custo

Para 10 réplicas com configuração de SDK de 128Mi/100m:

Suporte e manutenção

Abordagem híbrida

Você pode combinar ambas as abordagens dentro da mesma arquitetura: usar Microsoft.Identity.Web para serviços .NET que exigem desempenho máximo, aproveitando o SDK do Microsoft Entra para AgentID para serviços non-.NET ou quando precisar de padrões de autenticação independente de idioma. Essa estratégia híbrida permite otimizar o desempenho quando crítico, mantendo a consistência e a flexibilidade em todo o ecossistema de serviços.

Uma arquitetura de exemplo seria a seguinte:

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

Próximas etapas

• Guia de instalação – Implantar o SDK do Microsoft Entra para AgentID
• Referência de configuração – Configurar o SDK
• Cenários – Exemplos práticos
• Documentação do Microsoft.Identity.Web – Saiba mais sobre a biblioteca em processo