Perguntas frequentes sobre o Microsoft Entra SDK para AgentID

Perguntas gerais

O que é o Microsoft Entra SDK para AgentID?

O Microsoft Entra SDK para Agent ID é um serviço web containerizado que gere a aquisição de tokens, validação e chamadas seguras de API downstream. Ele é executado como um contêiner complementar junto com seu aplicativo, permitindo que você descarregue a lógica de identidade para um serviço dedicado. Ao centralizar as operações de identidade no SDK, você elimina a necessidade de incorporar 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.

Porque é que eu usaria o Microsoft Entra SDK para o ID do Agente em vez da Microsoft? Identidade.Web?

Característica Microsoft. Identity.Web Microsoft Entra SDK for Agent ID
Suporte de idiomas Apenas C# / .NET Qualquer idioma (HTTP)
Implementação Biblioteca em processo Contentor separado
Aquisição de Tokens Direto MSAL.NET Via HTTP API
Cache de token In-memory, distribuído In-memory, distribuído
Fluxo OBO Apoio indígena Via endpoint HTTP
Credenciais do cliente Apoio indígena Via endpoint HTTP
Identidade Gerenciada Apoio direto Apoio direto
Identidades do agente Via extensões Parâmetros de consulta
Validação de Token Middleware /Validar endpoint
API a jusante IDownstreamApi /endpoint Downstream Api
Microsoft Graph Integração com SDK de grafos Via Downstream Api
Desempenho Em processo (mais rápido) Overhead HTTP
Configuration appsettings.json e código appsettings.json e Variáveis de ambiente
Depuração Depuração .NET padrão Depuração de contêiner
Hot Reload .NET Hot Reload Reinício do contentor
Atualizações de pacotes Pacotes NuGet Imagens de contêiner
Licença MIT MIT

Consulte o Guia de comparação para obter orientações detalhadas.

O SDK Microsoft Entra para Agent ID está pronto para produção?

Sim, o SDK está pronto para produção. Consulte os lançamentos GitHub para o estado de lançamento mais recente e as diretrizes de prontidão para produção.

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

Sim - Consulte o Guia de Instalação para obter as imagens disponíveis e as tags de versão.

Posso executar o SDK fora do Kubernetes?

Sim - consulte o Instalação para instruções sobre como executar o SDK no Docker Compose ou noutros ambientes de contentores (Docker Compose, Azure Container Instances, AWS ECS/Fargate, Standalone Docker).

Quais portas de rede o SDK usa?

Porta padrão: 5000 (configurável)

O SDK só deve ser acessível a partir 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 recursos?

Consulte o Guia de Instalação para requisitos detalhados de recursos.

Posso usar o SDK com o Docker Compose?

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

Como faço para implantar no AKS com Identidade Gerenciada?

Sim – siga o Guia de Instalação na secção Azure Kubernetes Service (AKS) com Identidade Gerida.

Configuração

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

Está disponível uma referência de configuração?

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

Devo usar segredos de cliente ou certificados?

Prefira certificados em vez de segredos de cliente:

  • Mais seguro
  • Mais fácil de rodar
  • Recomendado pela Microsoft

Melhor: Usar Identidade Gerida em Azure (não são necessárias credenciais)

Consulte Práticas recomendadas de segurança para obter orientações.

Posso configurar várias APIs downstream?

Yes. 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 faço para 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 Referência de configuração para todas as opções.

Identidades dos agentes

As identidades de agente permitem 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 agentes?

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

  • De forma autónoma - no seu próprio contexto de aplicação
  • Interativo - em nome do usuário que o chamou

Consulte Identidades de agente para obter 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 de usuário
  • Tarefas em segundo plano
  • Operações sistema-a-sistema
  • Tarefas agendadas

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 qual usuário o agente opera em nome de. Ele requer AgentIdentity especificar qual contexto de agente usar. Sem AgentIdentity, o parâmetro não tem significado.

Por que AgentUsername e AgentUserId são mutuamente exclusivos?

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

  • AgentUsername - Nome Principal do Usuário (UPN)
  • AgentUserId - ID do objeto (OID)

Permitir ambos cria ambiguidade. Escolha o que se adapta ao seu cenário:

  • Use AgentUsername quando tiver o UPN do usuário
  • Use AgentUserId quando você tiver o ID do objeto do usuário

Utilização 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 declarações de retorno
  • /AuthorizationHeader/{serviceName} - Obter cabeçalho de autorização com token
  • /AuthorizationHeaderUnauthenticated/{serviceName} - Obter token sem token de usuário de entrada
  • /DownstreamApi/{serviceName} - Ligue diretamente para a API downstream
  • /DownstreamApiUnauthenticated/{serviceName} - Chamar API downstream sem token de usuário de entrada
  • /healthz - Sonda de saúde

Consulte Referência de pontos de extremidade para obter detalhes.

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

Autenticado: Requer 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 faço para validar um token de usuário?

GET /Validate
Authorization: Bearer <user-token>

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

Como posso obter um token de acesso para uma API downstream?

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

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

Posso substituir o método HTTP ou 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 tokens redundantes.

Os tokens de cache do SDK?

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é perto da expiração e, em seguida, atualizados automaticamente. A duração exata depende da vida útil dos tokens (tipicamente 1 hora para tokens Entra ID).

Posso desativar o cache?

O cache de token é automático e otimizado. Atualmente, não há nenhuma opção para desativá-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 implementações seguras de SDK seguem as melhores práticas de identidade e proteção de dados da Microsoft Entra, incluindo uso gerido de identidade, isolamento de rede e tratamento adequado de credenciais.

É seguro executar o SDK?

Sim - consulte as Práticas recomendadas de segurança para obter informações sobre as práticas recomendadas de segurança.

Devo expor o SDK externamente?

Nunca - O SDK só deve ser acessível a partir do contêiner do aplicativo. Para obter práticas recomendadas de segurança detalhadas, consulte Práticas recomendadas de segurança.

Como devo proteger o SDK?

Consulte Práticas recomendadas de segurança para obter orientações abrangentes.

Que credenciais devo usar?

Ordem de preferência:

  1. Managed Identity (Azure) - Mais seguro, sem credenciais
  2. Certificados - Seguros, podem ser rodados
  3. Segredos do Cliente - Menos preferido, mantenha em cofre seguro

O SDK é certificado em conformidade?

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

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 50 ms para tokens armazenados em cache.

Qual é o impacto no desempenho do uso do SDK?

HTTP típico ida e volta: 10-50ms

O cache de token minimiza aquisições repetidas. A primeira solicitação é mais lenta (aquisição de token), as 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 de rede), mas o SDK fornece:

  • Acesso agnóstico à língua
  • 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?

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

Migration

A sair da Microsoft. O Identity.Web para o SDK oferece vantagens em suporte multi-língua, configuração centralizada e escalabilidade simplificada entre serviços.

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

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

Support

Obtenha ajuda com problemas, encontre documentação adicional e aceda aos recursos da comunidade através dos canais oficiais.

Onde reporto bugs?

Reporte problemas no repositório GitHub, usando o modelo Entra ID.

Solução de problemas

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

Conteúdo relacionado

  • Last updated on