Referência de configuração: Microsoft Entra SDK para definições de ID de agente

Este guia fornece opções de configuração para o Microsoft Entra SDK para o AgentID, um serviço de autenticação containerizada que trata da aquisição e gestão de tokens para aplicações em ambientes containerizados. O SDK simplifica a integração de identidade ao gerir a autenticação do Microsoft Entra ID, fluxos de tokens on-behalf-of (OBO) e chamadas de API a jusante sem exigir que as aplicações incorporem diretamente as bibliotecas de autenticação.

Embora este guia se foque nos padrões de implementação do Kubernetes, o SDK pode ser implementado em qualquer ambiente containerizado, incluindo Docker, Azure Container Instances e outras plataformas de orquestração de contentores.

Se está a implementar no Azure Kubernetes Service (AKS), a configurar ambientes de desenvolvimento ou a configurar cargas de trabalho, esta referência abrange padrões de configuração, tipos de credenciais e variáveis de ambiente necessárias para proteger as suas aplicações com o Microsoft Entra ID.

Descrição geral da configuração

O Microsoft Entra SDK para Agent ID é configurado usando fontes de configuração seguindo as convenções ASP.NET Core. Os valores de configuração podem ser fornecidos através de vários métodos, incluindo:

• Variáveis de ambiente (recomendado para Kubernetes)
• Entra ID configuração - ficheiro appsettings.json anexado ao contentor ou incorporado no ficheiro yaml.
• Argumentos de linha de comando
• Azure App Configuration ou Key Vault (para cenários avançados)

Definições do Core Entra ID

O Microsoft Entra SDK para implementações de Agent ID requer definições centrais do Entra ID para autenticar tokens recebidos e adquirir tokens para APIs posteriores. Use as credenciais de cliente apropriadas no seguinte formato YAML, normalmente como variáveis de ambiente, para garantir a autenticação segura.

Configuração necessária

Primeiro, configure as definições centrais do Entra ID para o SDK para autenticar tokens recebidos e adquirir tokens para APIs a jusante.

env:
- name: AzureAd__Instance
  value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

Configuração de credenciais do cliente

O Microsoft Entra SDK para Agent ID suporta múltiplos tipos de credenciais de cliente para autenticação com o Microsoft Entra ID ao adquirir tokens para APIs downstream. Escolha o tipo de credencial que melhor se adapta ao seu ambiente de implantação e aos requisitos de segurança e certifique-se de que a configuração escolhida seja apropriada para o seu cenário.

Cada tipo de credencial atende a diferentes cenários:

• Segredo do cliente: Configuração simples para desenvolvimento e testes (não recomendado para produção)
• Key Vault Certificate: Ambientes de produção com gestão centralizada de certificados
• Certificado de arquivo: Quando os certificados são montados como arquivos (por exemplo, via segredos do Kubernetes)
• Certificate Store: Windows ambientes com armazenamento de certificados
• Workload Identity for Containers: Recomendado para AKS, usando ID de carga de trabalho Microsoft Entra com projeção de tokens baseada em ficheiros
• Identidade Gerida para VMs/Serviços de Aplicação: Serviços de Máquinas Virtuais do Azure e Aplicações com identidades geridas atribuídas pelo sistema ou pelo utilizador (não para contentores)

Configure uma ou mais fontes de credenciais no seguinte formato YAML:

Segredo do cliente

Esta configuração configura a autenticação Entra ID usando um cliente secret para autenticação serviço-a-serviço.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
  value: "<your-client-secret>"

Certificado da Key Vault

Esta configuração configura a autenticação Entra ID usando um certificado armazenado no Azure Key Vault.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://<your-keyvault>.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "<certificate-name>"

Certidão do ficheiro

Esta configuração configura a autenticação Entra ID usando um certificado armazenado como ficheiro.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "Path"
- name: AzureAd__ClientCredentials__0__CertificateDiskPath
  value: "/path/to/certificate.pfx"
- name: AzureAd__ClientCredentials__0__CertificatePassword
  value: "<certificate-password>"

Certificado da loja

Esta configuração configura a autenticação Entra ID usando um certificado da loja local de certificados.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "StoreWithThumbprint"
- name: AzureAd__ClientCredentials__0__CertificateStorePath
  value: "CurrentUser/My"
- name: AzureAd__ClientCredentials__0__CertificateThumbprint
  value: "<thumbprint>"

Identidade da carga de trabalho para contêineres (recomendado para AKS)

Esta configuração configura a autenticação Entra ID usando o ID de carga de trabalho Microsoft Entra para implementações containerizadas (AKS). Essa é a abordagem recomendada para cenários baseados em contêiner, pois usa projeção de token baseada em arquivo.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Nota: O caminho do ficheiro de token /var/run/secrets/azure/tokens/azure-identity-token ou uma variável de ambiente é projetado automaticamente pelo webhook Azure Workload Identity quando o seu pod está devidamente configurado com a anotação da conta de serviço e o rótulo do pod. Consulte Usando o Managed Identity para obter instruções de configuração completas.

Identidade gerenciada para VMs e Serviços de Aplicativo

Para cenários clássicos Azure de Identidade Gerida em Máquinas Virtuais ou Serviços de Aplicação (não contentores), use SignedAssertionFromManagedIdentity:

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
  value: "<managed-identity-client-id>"

Importante: Não use SignedAssertionFromManagedIdentity para ambientes em contêineres (Kubernetes, AKS, Docker). Para AKS, use SignedAssertionFilePath como mostrado acima. Para Kubernetes e Docker, use certificados de cliente. Para mais informações, consultar: https://aka.ms/idweb/client-credentials

Recursos adicionais

Para obter detalhes completos sobre todas as opções de configuração de credenciais e seu uso, consulte a especificação CredentialDescription no repositório microsoft-identity-abstractions-for-dotnet.

Prioridade de credenciais

Configure várias credenciais com seleção baseada em prioridades:

# First priority - Key Vault certificate
- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://prod-keyvault.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "prod-cert"

# Second priority - Client secret (fallback)
- name: AzureAd__ClientCredentials__1__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__1__ClientSecret
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: client-secret

O Microsoft Entra SDK para ID de Agente avalia as credenciais por ordem numérica (0, 1, 2, etc.) e utiliza a primeira credencial que autentica com sucesso.

Configuração de APIs downstream

Configure APIs downstream que seu aplicativo precisa chamar usando fluxos de token on-behalf-of (OBO). O Microsoft Entra SDK para Agent ID gere a aquisição de tokens e fornece cabeçalhos de autenticação para estas chamadas API. Cada API downstream requer um nome de configuração exclusivo e parâmetros específicos para aquisição de token e tratamento de solicitações HTTP.

Defina cada API downstream com sua URL base, escopos necessários e parâmetros opcionais. O SDK manipulará automaticamente a aquisição de token usando o token de usuário de entrada e fornecerá os cabeçalhos de autorização apropriados para as chamadas de API do seu aplicativo.

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

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

Opções de aquisição de tokens

Ajuste o comportamento de aquisição de tokens:

- name: DownstreamApis__Graph__AcquireTokenOptions__Tenant
  value: "<specific-tenant-id>"

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

- name: DownstreamApis__Graph__AcquireTokenOptions__CorrelationId
  value: "<correlation-id>"

Configuração de pedido HTTP assinado (SHR)

Habilite solicitações HTTP assinadas para maior segurança:

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopPublicKey
  value: "<base64-encoded-public-key>"

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopClaims
  value: '{"custom_claim": "value"}'

Configuração de registro em log

Configure os níveis de log:

- name: Logging__LogLevel__Default
  value: "Information"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Debug"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Warning"

Definições ASP.NET Core

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: ASPNETCORE_URLS
  value: "http://+:5000"

Per-Request substituições de configuração

Todos os pontos de extremidade de aquisição de token aceitam parâmetros de consulta para substituir a configuração:

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

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

GET /AuthorizationHeaderUnauthenticated/Graph?optionsOverride.RequestAppToken=true

# Override tenant
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>

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

# Enable SHR for this request
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>

Substituições de identidade de agente

Especifique a identidade do agente no momento da solicitação:

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

# Autonomous agent with specific agent user identity (by username)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

# Autonomous agent with specific agent user identity (by object ID)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUserId=<user-object-id>

Regras importantes:

• AgentUsername e AgentUserId requerer AgentIdentity
• AgentUsername e AgentUserId excluem-se mutuamente

Consulte Identidades de agente para obter semântica detalhada.

Exemplo de configuração completa

A seguir é apresentado um exemplo pronto para produção mostrando como implantar o SDK com separação adequada de configuração e segredos. Este exemplo demonstra a configuração de várias APIs downstream, o uso do Kubernetes ConfigMaps para configurações não confidenciais, o armazenamento seguro de credenciais em Secrets e a aplicação de configurações específicas do ambiente para implantação segura.

Esse padrão segue as práticas recomendadas do Kubernetes, separando dados de configuração de credenciais confidenciais, permitindo o gerenciamento eficaz de diferentes ambientes e mantendo a segurança.

Kubernetes ConfigMap

O ConfigMap armazena definições de configuração não sensíveis para o SDK, incluindo definições do Entra ID, APIs downstream e níveis de registo.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  ASPNETCORE_ENVIRONMENT: "Production"
  ASPNETCORE_URLS: "http://+:5000"
  
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "common"
  AzureAd__ClientId: "your-app-client-id"
  AzureAd__Scopes: "access_as_user"
  
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  
  DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
  DownstreamApis__MyApi__Scopes: "api://myapi/.default"
  
  Logging__LogLevel__Default: "Information"
  Logging__LogLevel__Microsoft.Identity.Web: "Debug"

Segredo do Kubernetes

O Secret armazena credenciais confidenciais, como segredos de cliente, separadamente do ConfigMap.

apiVersion: v1
kind: Secret
metadata:
  name: sidecar-secrets
type: Opaque
stringData:
  AzureAd__ClientCredentials__0__ClientSecret: "your-client-secret"

Implantação com ConfigMap e segredo

A implantação monta o ConfigMap e o Secret no contêiner do SDK, garantindo que a configuração e as credenciais estejam separadas corretamente.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        envFrom:
        - configMapRef:
            name: sidecar-config
        - secretRef:
            name: sidecar-secrets

Configuração específica do ambiente

Configure configurações específicas do ambiente para personalizar a segurança, o registro em log e o isolamento de locatários para seus ambientes de implantação. Cada ambiente requer diferentes abordagens de configuração para equilibrar a eficiência do desenvolvimento, a validação de preparo e os requisitos de segurança da produção.

Desenvolvimento

- name: ASPNETCORE_ENVIRONMENT
  value: "Development"
- name: Logging__LogLevel__Default
  value: "Debug"
- name: AzureAd__TenantId
  value: "<dev-tenant-id>"

Staging

- name: ASPNETCORE_ENVIRONMENT
  value: "Staging"
- name: Logging__LogLevel__Default
  value: "Information"
- name: AzureAd__TenantId
  value: "<staging-tenant-id>"

Produção

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"
- name: AzureAd__TenantId
  value: "<prod-tenant-id>"
- name: ApplicationInsights__ConnectionString
  value: "<app-insights-connection>"

Validation

O Microsoft Entra SDK para ID de Agente valida a configuração no arranque e regista erros para:

• Configurações necessárias ausentes (TenantId, ClientId)
• Configurações de credenciais inválidas
• Definições de API a jusante malformadas
• URLs ou formatos de escopo inválidos

Verifique os logs de contêiner para mensagens de validação:

kubectl logs <pod-name> -c sidecar

Melhores práticas

1. Use Secrets for Credentials: Armazena segredos e certificados de clientes no Kubernetes Secrets ou Azure Key Vault. Ver também https://aka.ms/msidweb/client-credentials
2. Configuração separada por ambiente: use o ConfigMaps para gerenciar configurações específicas do ambiente
3. Habilitar registro em log apropriado: usar o log de depuração no desenvolvimento, informações/avisos na produção
4. Configurar verificações de integridade: verifique se os pontos de extremidade de verificação de integridade estão configurados corretamente
5. Use Identidade de Carga de Trabalho para Containers: Para implementações containerizadas (AKS), prefira ID de carga de trabalho Microsoft Entra com SignedAssertionFilePath em vez de segredos de cliente para maior segurança
6. Use Identidade Gerida para VMs/Serviços de Aplicação: Para VMs e Serviços de Aplicações Azure, utilize identidades geridas atribuídas pelo sistema ou pelo utilizador
7. Validar no momento da implantação: testar a configuração no preparo antes da implantação da produção

Conteúdo relacionado

• Identidades do agente
• Referência de endpoints
• Práticas recomendadas de segurança
• Troubleshooting