Comparação: Microsoft Entra ID SDK de Autenticação (sidecar) vs. In-Process Microsoft. Identity.Web

Este guia ajuda você a identificar as diferenças entre o Microsoft Entra ID Auth SDK (sidecar) e a biblioteca Microsoft.Identity.Web em processo para gerenciar 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 de Autenticação Microsoft Entra ID (sidecar) é 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 de autenticação Microsoft Entra ID (sidecar) 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 ID SDK de autenticação (sidecar) (fora de processo)

Este trecho de código demonstra como chamar o SDK de autenticação do Microsoft Entra ID (sidecar) a partir 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

A escolha entre o Microsoft.Identity.Web e o SDK de autenticação do Microsoft Entra ID (sidecar) 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 o SDK de autenticação do Microsoft Entra ID (sidecar)

Em determinados cenários, talvez você queira migrar um aplicativo .NET existente que usa Microsoft. Identity.Web para aproveitar o SDK de Autenticação Microsoft Entra ID (sidecar) 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 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 ID Auth SDK (sidecar)
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 no processo para o Microsoft.Identity.Web e substitua-as por chamadas HTTP para os pontos de extremidade do SDK de autenticação do Microsoft Entra ID (sidecar):

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, você verá chamadas ao SDK de autenticação do Microsoft Entra ID (sidecar) usando o ponto de extremidade /DownstreamApi para obter os 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 inteiramente a validação ao SDK de autenticação do Microsoft Entra ID (sidecar).

// 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 de autenticação do Microsoft Entra ID (sidecar) introduz uma 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, a flexibilidade e o design que independe de linguagem do SDK de autenticação do Microsoft Entra ID (sidecar) podem superar as perdas de desempenho em muitos cenários.

A tabela a seguir mostra algumas comparações de desempenho e custo entre o uso no processo e o uso do SDK de autenticação do Microsoft Entra ID (sidecar) (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 .NET que exigem máximo desempenho e use o SDK de Autenticação do Microsoft Entra ID (sidecar) para serviços que não sejam .NET ou quando você precisar de padrões de autenticação independentes de linguagem. 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 ID Auth SDK (sidecar)</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