Resolução de problemas: problemas comuns do SDK Microsoft Entra para AgentID

Soluções para problemas operacionais e de implantação comuns do SDK.

Diagnóstico Rápido

Verificar a integridade do SDK

# Check if SDK is running
kubectl get pods -l app=myapp

# Check SDK logs
kubectl logs <pod-name> -c sidecar

# Test health endpoint
kubectl exec <pod-name> -c sidecar -- curl http://localhost:5000/health

Verificar configuração

# View SDK environment variables
kubectl exec <pod-name> -c sidecar -- env | grep AzureAd

# Check ConfigMap
kubectl get configmap sidecar-config -o yaml

# Check Secrets
kubectl get secret sidecar-secrets -o yaml

Problemas comuns

O contêiner não inicia

Sintoma

O pod mostra status CrashLoopBackOff ou Error.

Causas possíveis

Configuração necessária ausente

# Check logs for configuration errors
kubectl logs <pod-name> -c sidecar

# Look for messages like:
# "AzureAd:TenantId is required"
# "AzureAd:ClientId is required"

Solução:

# Ensure all required configuration is set
env:
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

Configuração de credencial inválida

# Check for credential errors in logs
kubectl logs <pod-name> -c sidecar | grep -i "credential"

Solução: verifique a configuração de credenciais e o acesso ao Key Vault ou aos segredos.

Conflito de porta

# Check if port 5000 is already in use
kubectl exec <pod-name> -c sidecar -- netstat -tuln | grep 5000

Solução: alterar a porta do SDK, se necessário:

env:
- name: ASPNETCORE_URLS
  value: "http://+:5001"

401 Erros não autorizados

Sintoma

As solicitações para o SDK retornam 401 Não autorizado.

Causas possíveis

Cabeçalho de Autorização ausente

# Test with curl
curl -v http://localhost:5000/AuthorizationHeader/Graph
# Should show 401 because no Authorization header

Solução: incluir cabeçalho de autorização:

curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Graph

Token inválido ou expirado

# Check token claims
kubectl exec <pod-name> -c sidecar -- curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/Validate

Solução: obtenha um novo token da ID do Microsoft Entra.

Incompatibilidade de audiência

# Check logs for audience validation errors
kubectl logs <pod-name> -c sidecar | grep -i "audience"

Solução: verificar se a configuração de público corresponde ao token:

env:
- name: AzureAd__Audience
  value: "api://<your-api-id>"

Falha de validação de escopo

# Check logs for scope errors
kubectl logs <pod-name> -c sidecar | grep -i "scope"

Solução: verifique se o token contém escopos necessários:

env:
- name: AzureAd__Scopes
  value: "access_as_user"  # Or remove to disable scope validation

Para entender os erros detalhados, talvez seja necessário aumentar o nível de log:

Logging__LogLevel__Default=Debug 
Logging__LogLevel__Microsoft.Identity.Web=Debug 
Logging__LogLevel__Microsoft.AspNetCore=Debug 

400 Solicitação incorreta – Validação de identidade do agente

Sintoma

As solicitações com parâmetros de identidade do agente retornam 400 Solicitações Incorretas.

Erro: AgentUsername sem AgentIdentity

Solicitação:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentUsername=user@contoso.com"

Resposta de erro:

{
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

Solução: incluir o parâmetro AgentIdentity:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<client-id>&AgentUsername=user@contoso.com"

Erro: AgentUsername e AgentUserId foram ambos especificados

Solicitação:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUsername=user@contoso.com&AgentUserId=<oid>"

Resposta de erro:

{
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

Solução: use apenas um:

# Use AgentUsername
curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUsername=user@contoso.com"

# OR use AgentUserId
curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUserId=<oid>"

Erro: Formato AgentUserId inválido

Solicitação:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUserId=invalid-guid"

Resposta de erro:

{
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

Solução: forneça um GUID válido:

curl -H "Authorization: Bearer <token>" \
  "http://localhost:5000/AuthorizationHeader/Graph?AgentIdentity=<id>&AgentUserId=12345678-1234-1234-1234-123456789012"

404 Não encontrado – Serviço não configurado

Sintoma

{
  "status": 404,
  "detail": "Downstream API 'UnknownService' not configured"
}

Causas possíveis

Erro de digitação do nome do serviço

# Wrong service name in URL
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Grafh
# Should be "Graph"

Solução: Use o nome do serviço correto da configuração.

Configuração ausente de DownstreamApis

Solução: adicionar configuração de serviço:

env:
- name: DownstreamApis__Graph__BaseUrl
  value: "https://graph.microsoft.com/v1.0"
- name: DownstreamApis__Graph__Scopes
  value: "User.Read"

Falhas de aquisição de token

Sintoma

500 Erro interno do servidor ao adquirir tokens.

Códigos de erro do AADSTS

AADSTS50076: Autenticação Multifator necessária

AADSTS50076: Due to a configuration change made by your administrator, 
or because you moved to a new location, you must use multi-factor authentication.

Solução: o usuário deve concluir a MFA. Esse é o comportamento esperado para políticas de acesso condicional.

AADSTS65001: Consentimento do Usuário Necessário

AADSTS65001: The user or administrator has not consented to use the application.

Solução:

1. Solicitar consentimento do administrador para o aplicativo
2. Verifique se as permissões delegadas estão configuradas corretamente

AADSTS700016: Aplicativo não encontrado

AADSTS700016: Application with identifier '<client-id>' was not found.

Solução: Verifique se o ClientId está correto e se o aplicativo existe no inquilino.

AADSTS7000215: Segredo do Cliente Inválido

AADSTS7000215: Invalid client secret is provided.

Solução:

1. Verificar se o segredo do cliente está correto
2. Verificar se o segredo expirou
3. Gerar novo segredo e atualizar a configuração.

AADSTS700027: Certificado ou Chave Privada Não Configurada

AADSTS700027: The certificate with identifier '<thumbprint>' was not found.

Solução:

1. Verificar se o certificado está registrado no registro do aplicativo
2. Verificar a configuração do certificado no SDK
3. Verifique se o certificado está acessível no contêiner

Problemas de cache de token

Solução: limpar o cache de token e reiniciar:

kubectl rollout restart deployment <deployment-name>

Para cache distribuído (Redis):

# Clear Redis cache
redis-cli FLUSHDB

Problemas de conectividade de rede

Não é possível acessar a ID do Microsoft Entra

Sintoma: erros de tempo limite ao adquirir tokens.

Diagnóstico:

# Test connectivity from SDK container
kubectl exec <pod-name> -c sidecar -- curl -v https://login.microsoftonline.com

# Check DNS resolution
kubectl exec <pod-name> -c sidecar -- nslookup login.microsoftonline.com

Solução:

• Verificar políticas de rede
• Verifique se as regras do firewall permitem o protocolo HTTPS para o login.microsoftonline.com.
• Verifique se o DNS está funcionando corretamente

Não é possível alcançar APIs downstream

Diagnóstico:

# Test connectivity to downstream API
kubectl exec <pod-name> -c sidecar -- curl -v https://graph.microsoft.com

# Check configuration
kubectl exec <pod-name> -c sidecar -- env | grep DownstreamApis__Graph__BaseUrl

Solução:

• Verificar se a URL da API downstream está correta
• Verificar regras de saída de rede
• Verifique se a API está acessível no cluster

O aplicativo não pode acessar o SDK

Sintoma

O aplicativo mostra erros de conexão ao chamar o SDK.

Diagnóstico:

# Test from application container
kubectl exec <pod-name> -c app -- curl -v http://localhost:5000/health

# Check if sidecar is listening
kubectl exec <pod-name> -c sidecar -- netstat -tuln | grep 5000

Solução:

• Verificar a variável de ambiente SIDECAR_URL
• Verifique se o SDK está em execução: kubectl get pods
• Verifique se a porta 5000 não está bloqueada

Problemas de desempenho

Aquisição lenta de token

Diagnóstico:

# Enable detailed logging
# Add to SDK configuration:
# - name: Logging__LogLevel__Microsoft.Identity.Web
#   value: "Debug"

# Check logs for timing information
kubectl logs <pod-name> -c sidecar | grep "Token acquisition"

Soluções:

1. Verificar Cache de Token: verifique se o cache está habilitado e funcionando
2. Aumentar recursos: alocar mais CPU/memória para o SDK
3. Latência de Rede: verificar a latência para a Identidade Microsoft Entra
4. Pool de Conexões: verificar a reutilização da conexão HTTP

Alto uso de memória

Diagnóstico:

# Check resource usage
kubectl top pod <pod-name> --containers

# Check for memory leaks in logs
kubectl logs <pod-name> -c sidecar | grep -i "memory"

Soluções:

1. Aumentar os limites de memória
2. Verificar se há problemas de tamanho de cache de token
3. Examinar os padrões de uso do aplicativo
4. Considere o cache distribuído para várias réplicas

Problemas de certificado

Certificado não encontrado

Sintoma:

Certificate with thumbprint '<thumbprint>' not found in certificate store.

Solução:

• Verificar se o certificado está montado corretamente
• Verificar o caminho do repositório de certificados
• Verifique se as permissões de certificado estão corretas

Certificado expirado

Sintoma:

The certificate has expired.

Solução:

1. Gerar novo certificado
2. Registrar-se na ID do Microsoft Entra
3. Atualizar configuração do SDK
4. Reimplantar contêineres

Acesso do Key Vault negado

Sintoma:

Access denied to Key Vault '<vault-name>'.

Solução:

• Verificar se a identidade gerenciada tem política de acesso ao Key Vault
• Verificar regras de firewall do Key Vault
• Certificar-se de que o certificado exista no Key Vault

Problemas de solicitação HTTP assinada (SHR)

Token PoP inválido

Sintoma: A API Downstream rejeita o token PoP.

Diagnóstico:

# Check if PoP token is being requested
kubectl logs <pod-name> -c sidecar | grep -i "pop"

# Verify PopPublicKey is configured correctly
kubectl exec <pod-name> -c sidecar -- env | grep PopPublicKey

Solução:

• Verificar se a chave pública está codificada corretamente em base64
• Garantir que a API downstream dê suporte a tokens PoP
• Verificar o formato do token PoP

Chave privada ausente

Sintoma: não é possível assinar a solicitação HTTP.

Solução: verifique se a chave privada está disponível para o aplicativo para solicitações de assinatura.

Tabela de referência de erro

Ferramentas de Depuração

Habilitar registro em log detalhado

env:
- name: Logging__LogLevel__Default
  value: "Debug"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Trace"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Debug"

Aviso: o logging de depuração/rastreamento pode registrar informações confidenciais. Use apenas durante o desenvolvimento ou de forma temporária em produção.

Validação de token de teste

# Validate token
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/Validate | jq .

# Check claims
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/Validate | jq '.claims'

Testar aquisição de token

# Get authorization header
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Graph | jq .

# Extract and decode token
curl -H "Authorization: Bearer <token>" \
  http://localhost:5000/AuthorizationHeader/Graph | \
  jq -r '.authorizationHeader' | \
  cut -d' ' -f2 | \
  jwt decode -

Monitorar com Application Insights

Se configurado:

# Query Application Insights
az monitor app-insights query \
  --app <app-insights-name> \
  --analytics-query "traces | where message contains 'token acquisition' | take 100"

Obtendo ajuda

Coletar informações de diagnóstico

Ao abrir um problema, inclua:

1. Versão do SDK:

   kubectl describe pod <pod-name> | grep -A 5 "sidecar:"
   

2. Configuração (redigir dados confidenciais):

   kubectl get configmap sidecar-config -o yaml
   

3. Logs (últimas 100 linhas):

   kubectl logs <pod-name> -c sidecar --tail=100
   

4. Mensagens de erro: resposta completa de erro do SDK

5. Detalhes da solicitação: método HTTP, ponto de extremidade, parâmetros usados

Recursos de suporte

• Problemas do GitHub: microsoft-identity-web/issues
• Microsoft Q&A: Microsoft Identity Platform
• Stack Overflow: Tag [microsoft-identity-web]

Práticas recomendadas para solução de problemas

1. Comece com a Verificação de Integridade: sempre verifique se o SDK está íntegro primeiro
2. Logs de verificação: os logs do SDK contêm informações valiosas de diagnóstico
3. Verificar Configuração: verifique se todas as configurações necessárias estão presentes e corretas
4. Teste incrementalmente: comece com solicitações simples, adicione complexidade gradualmente
5. Usar IDs de correlação: incluir IDs de correlação para rastreamento entre serviços
6. Monitorar continuamente: configurar alertas para falhas de autenticação
7. Problemas de documento: manter anotações sobre problemas e resoluções para referência futura

Recursos relacionados

• Guia de instalação
• Referência de configuração
• Práticas recomendadas de segurança
• perguntas frequentes