SDK do Microsoft Entra para AgentID - Visão geral

O SDK do Microsoft Entra para AgentID é um serviço web em contêiner que manipula a aquisição de token, a validação e as chamadas de api downstream seguras. 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 AgentID, 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 AgentID fornecerá uma maneira padronizada de lidar com autenticação e autorização em aplicativos nativos de nuvem.

O que é o SDK do Microsoft Entra para AgentID?

O SDK do Microsoft Entra para AgentID 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 AgentID 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 cliente → sua API Web → Microsoft Entra SDK for AgentID → 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 do Microsoft Entra para implantação do AgentID 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 AgentID, 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 AgentID ou Microsoft.Identity.Web

Consulte Comparação com Microsoft.Identity.Web para obter diretrizes detalhadas sobre como escolher entre as duas abordagens.

Validação de token

O SDK Microsoft Entra para AgentID valida tanto tokens de acesso quanto tokens de ID emitidos pelo Microsoft Entra ID, verificando suas assinaturas em relação às chaves públicas do Microsoft Entra ID, checando o tempo 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.

Criação de cabeçalho de aquisição/autorização de token

• 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
• Identidade Gerenciada – Autenticação de serviço nativa do Azure
• 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 do Microsoft Entra para AgentID 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 operações de identidade ao SDK do Microsoft Entra para AgentID por meio de pontos de extremidade 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 o Microsoft Entra ID para emissão de token e recuperação de metadados do Open ID Connect, com a arquitetura demonstrada no trecho de código a seguir.

%%{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 AgentID]:::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
• Confira os guias de solução de problemas do ID Microsoft Entra

Recursos adicionais

• Documentação do Microsoft Entra ID
• Documentação da Plataforma de Identidade da Microsoft
• Repositório Web do Microsoft Identity
• Documentação do Kubernetes
• Documentação do Docker