Visão geral do SDK do Microsoft Entra para ID do Agente

O SDK do Microsoft Entra para ID do Agente é um serviço web conteinerizado que lida com a aquisição, a validação e as chamadas seguras para APIs downstream. Ele é executado como um contêiner complementar ao lado do aplicativo, permitindo que você descarrege a lógica de identidade para um serviço dedicado. Centralizando as operações de identidade no SDK do Microsoft Entra para ID do Agente, você elimina a necessidade de inserir uma lógica de gerenciamento de token complexa em cada serviço, reduzindo a duplicação de código e possíveis vulnerabilidades de segurança.

Se você estiver criando com o Kubernetes, serviços em contêineres com o Docker ou microsserviços modernos no Azure, o SDK do Microsoft Entra para ID do Agente fornecerá uma maneira padronizada de lidar com autenticação e autorização em aplicativos nativos de nuvem.

Qual é o SDK do Microsoft Entra para a ID do Agente?

O SDK do Microsoft Entra para ID do Agente se comunica com seu aplicativo por meio de uma API HTTP para autenticação e autorização, fornecendo padrões de integração consistentes independentemente da pilha de tecnologia. Em vez de inserir a lógica de identidade diretamente no código do aplicativo, o SDK do Microsoft Entra para ID do Agente manipula o gerenciamento de tokens, a validação e as chamadas à API por meio de solicitações HTTP padrão.

Essa abordagem permite arquiteturas de microsserviços poliglotas em que diferentes serviços podem ser escritos em Python, Node.js, Go, Java e outros, mantendo padrões de autenticação consistentes.

A arquitetura típica é a seguinte:

Aplicativo do Cliente → Sua API Web → Microsoft Entra SDK para ID de Agente → Microsoft Entra ID

Para obter as marcas de versão e imagem de contêiner mais recentes, consulte a Imagem de Contêiner para começar.

Segurança

Verifique se o SDK Microsoft Entra para implantação de ID do Agente segue as práticas recomendadas para uma operação segura. O SDK deve ser executado em um ambiente em contêineres com acesso restrito à rede, para impedir o acesso não autorizado. Expor a API do SDK publicamente pode levar a vulnerabilidades de segurança, como aquisição de token não autorizado.

Consulte as Práticas Recomendadas de Segurança para garantir as melhores práticas para recomendações de segurança de rede, credencial e runtime.

Início rápido

Para começar a usar o SDK do Microsoft Entra para a ID do Agente, as seguintes etapas são recomendadas:

1. Escolha sua implantação – Selecione Kubernetes, Docker ou AKS
2. Definir configurações – Configurar variáveis de ambiente
3. Escolher um cenário – Siga um exemplo guiado
4. Implantar em produção – Examinar as práticas recomendadas de segurança

Principais benefícios

A arquitetura separa as preocupações de identidade da lógica de negócios, fornecendo os seguintes benefícios:

Quando usar o SDK do Microsoft Entra para ID do Agente ou Microsoft.Identity.Web

Consulte Comparison com Microsoft. Identity.Web para obter diretrizes detalhadas sobre como escolher entre as duas abordagens.

Validação de token

O SDK do Microsoft Entra para ID do Agente valida tokens de acesso e tokens de ID emitidos por Microsoft Entra ID, verificando suas assinaturas em relação às chaves públicas do Microsoft Entra ID, verificando os tempos de expiração e garantindo que os tokens sejam destinados ao seu aplicativo. Depois de validado, você pode extrair declarações, funções e escopos do usuário para tomar decisões de autorização informadas dentro da lógica do aplicativo.

Aquisição de token/criação de cabeçalho de autorização

• Fluxo On-Behalf-Of OAuth 2.0 – Delegar o contexto do usuário para as APIs de destino
• Credenciais do cliente – autenticação de aplicativo para aplicativo
• Managed Identity – Autenticação de serviço de Azure nativa
• Identidade do Agente – Padrões de agente autônomos ou delegados

Chamadas à API downstream

• Adquirir e anexar tokens automaticamente
• Sobrescrita de solicitações opcionais (escopos, método, cabeçalhos)
• Suporte a Solicitações HTTP assinadas (PoP/SHR)

Cenários e tutoriais

Os guias a seguir são tutoriais passo a passo abrangentes com exemplos práticos de código que demonstram como integrar o SDK Microsoft Entra para ID do Agente em seus aplicativos. Cada cenário fornece exemplos completos de solicitação/resposta, snippets de código e padrões de implementação personalizados para diferentes linguagens e estruturas de programação.

Padrões de arquitetura

Um fluxo típico em que seu cliente chama uma API Web, a API delega as operações de identidade ao Microsoft Entra SDK para Identificação de Agente por meio de endpoints HTTP. O SDK valida tokens de entrada usando o /Validate ponto de extremidade, adquire tokens usando /AuthorizationHeader e /AuthorizationHeaderUnauthenticated, e pode invocar diretamente APIs downstream usando /DownstreamApi e /DownstreamApiUnauthenticated.

Ele interage com Microsoft Entra ID para emissão de token e recuperação de metadados do Open ID Connect, com a arquitetura demonstrada no seguinte snippet de código:

%%{init: {
  "theme": "base",
  "themeVariables": {
    "background": "#121212",
    "primaryColor": "#1E1E1E",
    "primaryBorderColor": "#FFFFFF",
    "primaryTextColor": "#FFFFFF",
    "textColor": "#FFFFFF",
    "lineColor": "#FFFFFF",
    "labelBackground": "#000000"
  }
}}%%
flowchart LR
    classDef dnode fill:#1E1E1E,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    linkStyle default stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

    client[Client Application]:::dnode -->| Bearer over HTTP | webapi[Web API]:::dnode
    subgraph Pod / Host
        webapi -->|"/Validate<br/>/AuthorizationHeader/{name}<br/>/DownstreamApi/{name}"| sidecar[Microsoft Entra SDK for Agent ID]:::dnode
    end
    sidecar -->|Token validation & acquisition| entra[Microsoft Entra ID]:::dnode

Suporte e recursos

Os recursos a seguir fornecem diretrizes abrangentes e ajudam a solucionar problemas e respostas a perguntas comuns.

Para obter ajuda adicional:

• Relatar problemas no repositório Microsoft-identity-web
• Verifique Microsoft Entra ID guias de solução de problemas

Conteúdo relacionado

• Guia de instalação
• Referência de configuração
• Comparação com Microsoft.Identity.Web
• Práticas recomendadas de segurança