Perguntas frequentes sobre o SDK do Microsoft Entra para AgentID

Perguntas Gerais

O que é o SDK do Microsoft Entra para AgentID?

O SDK do Microsoft Entra para AgentID é um serviço Web em contêineres que manipula a aquisição, 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, 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.

Por que eu usaria o SDK do Microsoft Entra para AgentID em vez de Microsoft.Identity.Web?

Característica	Microsoft.Identity.Web	SDK do Microsoft Entra para AgentID
Suporte ao idioma	Somente C# /.NET	Qualquer idioma (HTTP)
Implantação	Biblioteca em processo	Contêiner separado
Aquisição de token	✅ Direct MSAL.NET	✅ Por meio da API HTTP
Cache de token	✅ Na memória, ✅ distribuído	✅ Na memória, ❌distribuído
Fluxo OBO	✅ Suporte nativo	✅ Por meio do ponto de extremidade HTTP
Credenciais do cliente	✅ Suporte nativo	✅ Por meio do ponto de extremidade HTTP
Identidade Gerenciada	✅ Suporte direto	✅ Suporte direto
Identidades do agente	✅ Por meio de extensões	✅ Parâmetros de consulta
Validação de token	✅ Middleware	✅ /Validar ponto de extremidade
Downstream API	✅ IDownstreamApi	✅ Ponto de extremidade /DownstreamApi
Microsoft Graph	✅ Integração do SDK do Graph	⚠️ Via DownstreamApi
Desempenho	⚡ Em processo (mais rápido)	🔄 Sobrecarga HTTP
Configuration	`appsettings.json` e código	`appsettings.json` e variáveis de ambiente
Depuração de	✅ Depuração padrão do .NET	⚠️ Depuração de contêiner
Recarga Rápida	✅ Recarregamento frequente do .NET	❌ Reinicialização do contêiner
Atualizações de pacote	📦 Pacotes NuGet	🐳 Imagens de contêiner
Licença	MIT	MIT

Consulte o Guia de Comparação para obter diretrizes detalhadas.

O SDK do Microsoft Entra para AgentID está pronto para produção?

Sim, o SDK está pronto para produção. Consulte as versões do GitHub para obter as diretrizes mais recentes de status de versão e preparação para produção.

As imagens de contêiner estão disponíveis?

Sim – consulte o Guia de Instalação para obter imagens e marcas de versão disponíveis.

Posso executar o SDK fora do Kubernetes?

Sim – consulte o Guia de Instalação para obter instruções sobre como executar o SDK no Docker Compose ou em outros ambientes de contêiner (Docker Compose, Instâncias de Contêiner do Azure, ECS/Fargate do AWS, Docker Autônomo).

Quais portas de rede o SDK usa?

Porta padrão: 5000 (configurável)

O SDK só deve ser acessível do contêiner do aplicativo, nunca exposto externamente.

Implantação

Saiba mais sobre opções de implantação, requisitos de recursos e integração com plataformas de contêiner, como Docker Compose e Kubernetes.

Quais são os requisitos de recurso?

Sim – consulte o Guia de Instalação para obter os requisitos de recursos.

Posso usar o SDK com o Docker Compose?

Sim - consulte o Guia de Instalação para exemplos do Docker Compose.

Como fazer para implantar no AKS com a Identidade Gerenciada?

Sim – siga o Guia de Instalação no AKS (Serviço de Kubernetes do Azure) com a seção Identidade Gerenciada .

Configuração

Defina as configurações do SDK, incluindo credenciais, APIs downstream e substituições de solicitação para corresponder aos requisitos de implantação.

Uma referência de configuração está disponível?

Sim – consulte a Referência de Configuração para obter opções de configuração detalhadas.

Devo usar segredos ou certificados do cliente?

Prefira certificados em vez de segredos do cliente:

Mais seguro
Mais fácil de girar
Recomendado pela Microsoft

Melhor: usar a Identidade Gerenciada no Azure (sem credenciais necessárias)

Consulte as práticas recomendadas de segurança para obter diretrizes.

Posso configurar várias APIs downstream?

Sim. Configure cada um com sua própria seção:

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
DownstreamApis__MyApi__Scopes: "api://myapi/.default"

Como substituir a configuração por solicitação?

Use parâmetros de consulta em pontos de extremidade:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Consulte a Referência de Configuração para todas as opções.

Identidades do agente

As identidades do agente habilitam cenários em que um aplicativo de agente pode operar de forma autônoma ou em nome de um usuário, com isolamento de contexto e escopo adequados.

O que são identidades de agente?

As identidades do agente habilitam cenários em que um aplicativo de agente atua:

De forma autônoma - em seu próprio contexto de aplicativo
Interativo – em nome do usuário que o chamou

Consulte as Identidades do Agente para obter uma documentação abrangente.

Quando devo usar o modo de agente autônomo?

Use o modo de agente autônomo para:

Processamento em lote sem contexto do usuário
Tarefas em segundo plano
Operações sistema a sistema
Trabalhos agendados

Exemplo:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

Quando devo usar o modo de agente interativo?

Use o modo de agente delegado para:

Aplicativos de agente interativos
Assistentes de IA atuando em nome dos usuários
Automação com escopo do usuário
Fluxos de trabalho personalizados

Exemplo:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

Por que não posso usar AgentUsername sem AgentIdentity?

AgentUsername é um modificador que especifica de qual usuário o agente opera em nome. Ele requer AgentIdentity especificar qual contexto de agente usar. Sem AgentIdentity, o parâmetro não tem nenhum significado.

Por que AgentUsername e AgentUserId são mutuamente exclusivos?

São duas maneiras de identificar o mesmo usuário:

AgentUsername - Nome da entidade de usuário (UPN)
AgentUserId - ID do objeto (OID)

Permitir ambos cria ambiguidade. Escolha aquele que se ajuste ao seu cenário:

Usar AgentUsername quando você tiver o UPN do usuário
Usar AgentUserId quando você tiver a ID do objeto do usuário

Uso da API

O SDK expõe vários pontos de extremidade HTTP para aquisição de token, validação e chamadas de API downstream com suporte para fluxos autenticados e não autenticados.

Quais pontos de extremidade o SDK expõe?

/Validate – Validar token e retornar declarações
/AuthorizationHeader/{serviceName} – Obter o cabeçalho de autorização com o token
/AuthorizationHeaderUnauthenticated/{serviceName} – Obter token sem token de usuário de entrada
/DownstreamApi/{serviceName} - Chamar a API downstream diretamente
/DownstreamApiUnauthenticated/{serviceName} – Chamar a API downstream sem token de usuário de entrada
/healthz - Investigação de integridade

Consulte a Referência de Pontos de Extremidade para obter detalhes.

Qual é a diferença entre pontos de extremidade autenticados e não autenticados?

Autenticado: exigir token de portador no Authorization cabeçalho (para fluxos OBO) Não autenticado: não valide o token de entrada (para cenários somente de aplicativo ou agente)

Como fazer para validar um token de usuário?

GET /Validate
Authorization: Bearer <user-token>

A resposta inclui todas as declarações do token.

Como obter um token de acesso para uma API downstream?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

A resposta inclui o cabeçalho de autorização pronto para uso com a API downstream.

Posso substituir o método HTTP ou o caminho por solicitação?

Sim, usando parâmetros de consulta:

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

# Override path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Cache de token

O SDK armazena automaticamente tokens em cache na memória para otimizar o desempenho e reduzir as solicitações de aquisição de token redundante.

O SDK armazena tokens em cache?

Sim - o SDK armazena tokens em cache na memória por padrão.

Por quanto tempo os tokens são armazenados em cache?

Os tokens são armazenados em cache até a expiração próxima e, em seguida, são atualizados automaticamente. A duração exata depende do tempo de vida do token (normalmente 1 hora para tokens de ID do Entra).

Posso desabilitar o cache?

O cache de token é automático e otimizado. No momento, não há nenhuma opção para desabilitá-lo.

O cache de token é compartilhado entre instâncias do SDK?

Não – cada instância do SDK mantém seu próprio cache na memória. Em implantações de alta disponibilidade, cada pod tem cache independente.

Segurança

As implantações seguras do SDK seguem as melhores práticas de identidade e proteção de dados do Microsoft Entra, incluindo uso de identidade gerenciada, isolamento de rede e tratamento adequado de credenciais.

É seguro executar o SDK?

Sim – consulte as práticas recomendadas de segurança para melhores práticas de segurança.

Devo expor o SDK externamente?

Nunca – o SDK só deve ser acessível no contêiner do aplicativo. Para obter práticas recomendadas de segurança detalhadas, consulte As práticas recomendadas de segurança.

Como devo proteger o SDK?

Consulte as Práticas Recomendadas de Segurança para obter diretrizes abrangentes.

Quais credenciais devo usar?

Ordem de preferência:

Identidade Gerenciada (Azure) – Mais segura, sem credenciais
Certificados – Seguros, podem ser girados
Segredos do cliente – menos preferencial, mantenha-se no cofre seguro

O SDK tem certificação de conformidade?

Verifique o repositório GitHub para obter informações de conformidade atuais.

Performance

O desempenho do SDK depende da eficácia do cache de tokens e da latência de ida e volta da rede, com tempos de resposta típicos entre 10 e 50ms para tokens armazenados em cache.

Qual é o impacto no desempenho do uso do SDK?

Viagem de ida e volta HTTP típica: 10-50ms

O cache de token minimiza aquisições repetidas. A primeira solicitação é mais lenta (aquisição de token), solicitações subsequentes usam tokens armazenados em cache.

Como o desempenho do SDK se compara às bibliotecas em processo?

As bibliotecas em processo são mais rápidas (sem ida e volta à rede), mas o SDK fornece:

Acesso independente de linguagem
Configuração centralizada
Cache de token compartilhado entre serviços
Dimensionamento simplificado

Consulte o Guia de Comparação para obter detalhes.

Posso dimensionar o SDK horizontalmente?

Sim. Implante várias réplicas do SDK usando a Implantação do Kubernetes. Cada pod mantém o cache de token independente.

Migration

A migração do Microsoft.Identity.Web para o SDK oferece vantagens em suporte de vários idiomas, configuração centralizada e dimensionamento simplificado entre serviços.

Posso migrar do Microsoft.Identity.Web para o SDK do Microsoft Entra para AgentID?

Sim - consulte o Guia de Comparação para obter etapas de migração detalhadas

Support

Obtenha ajuda com problemas, encontre documentação adicional e acesse recursos da comunidade por meio de canais oficiais.

Onde relatar bugs?

Relatar problemas no repositório GitHub usando o modelo de ID do Entra.

Resolução de problemas

Ao encontrar problemas com o SDK, consulte o guia de solução de problemas abrangente para etapas de diagnóstico, problemas comuns e soluções no Guia de Solução de Problemas.