Comparação: Microsoft Entra SDK para ID do Agente versus In-Process Microsoft. Identity.Web

Este guia ajuda você a identificar as diferenças entre o SDK do Microsoft Entra para a identificação do agente e a biblioteca em processo Microsoft.Identity.Web 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 desempenho. O SDK do Microsoft Entra para ID do Agente é executado como um contêiner separado e dá suporte a qualquer linguagem de programação por meio de APIs HTTP. 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 no processo do seu aplicativo. O SDK do Microsoft Entra para ID do Agente funciona como um serviço independente ao lado do aplicativo. Essa escolha arquitetônica afeta fatores como fluxo de trabalho de desenvolvimento e complexidade operacional.

Microsoft. Identity.Web (em processo)

Este snippet de código mostra como o Microsoft.Identity.Web integra-se 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);
    }
}

Microsoft Entra SDK para ID do Agente (fora do processo)

Este trecho de código demonstra como chamar o SDK do Microsoft Entra para ID do agente 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 Microsoft.Identity.Web e o SDK do Microsoft Entra para Agent ID depende dos requisitos, da arquitetura e da estratégia de implantação do seu aplicativo. Dependendo de suas necessidades, uma abordagem pode ser mais adequada do que a outra. As diretrizes a seguir podem ajudá-lo a tomar uma decisão informada.

Diretrizes de migração

Migrando de Microsoft. Identity.Web para Microsoft Entra SDK para AgentID

Em determinados cenários, talvez você queira migrar um aplicativo .NET existente que usa Microsoft.Identity.Web para utilizar o SDK do Microsoft Entra para autenticação por meio do Agent ID. 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 fazer essa alteração. 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, adicione 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, transfira 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 o código do aplicativo

Identifique todas as instâncias de chamadas em processo para Microsoft.Identity.Web e substitua-as por chamadas HTTP para o SDK Microsoft Entra nos endpoints de ID do agente:

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 trecho de código a seguir, são apresentadas chamadas para o SDK do Microsoft Entra para a Identificação do Agente usando o ponto de extremidade /DownstreamApi 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

Você pode implementar a mesma lógica 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 de Microsoft.Identity.Web

Depois de concluir as etapas anteriores, arrume seu aplicativo removendo os pacotes NuGet para 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 a configuração de autenticação original. Em vez disso, você pode 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: atualize os testes para simular chamadas HTTP para o SDK.
2. Testes de integração: teste a comunicação do SDK em ambiente de teste.
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

Sobrecarga do SDK

O SDK do Microsoft Entra para ID do agente introduz sobrecarga de comunicação HTTP.

Desempenho em Processo

Usando Microsoft. Identity.Web tem sobrecarga mínima, pois é executada no mesmo processo que seu aplicativo. Ele fornece 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. No entanto, o SDK Microsoft Entra para a flexibilidade do AgentID e seu design independente de linguagem podem compensar os compromissos de desempenho em muitos cenários.

A tabela a seguir mostra algumas comparações de desempenho e custo para uso em processo e uso Microsoft Entra SDK para ID do agente (fora do processo):

Considerações de custo

Exemplo de custo

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

Suporte e manutenção

Abordagem híbrida

Você pode combinar ambas as abordagens dentro da mesma arquitetura. Use Microsoft. Identity.Web para serviços de .NET que exigem o desempenho máximo e usam o SDK Microsoft Entra para ID do agente para serviços não .NET ou quando você precisa de padrões de autenticação independente de idioma. Essa estratégia híbrida ajuda você a otimizar o desempenho em que ele é crítico, mantendo a consistência e a flexibilidade em todo o ecossistema de serviços.

Uma arquitetura de exemplo é 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

Conteúdo relacionado

• Guia de instalação
• Referência de configuração
• Chamar Downstream API
• Visão geral