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

Este guia fornece opções de configuração para o SDK do Microsoft Entra para AgentID, um serviço de autenticação em contêineres que manipula a aquisição e o gerenciamento de tokens para aplicativos em ambientes em contêineres. O SDK simplifica a integração de identidade gerenciando Microsoft Entra ID autenticação, fluxos de token em nome de (OBO) e chamadas de API downstream sem exigir que os aplicativos insiram bibliotecas de autenticação diretamente.

Embora este guia se concentre nos padrões de implantação do Kubernetes, o SDK pode ser implantado em qualquer ambiente em contêineres, incluindo Docker, Instâncias de Contêiner do Azure e outras plataformas de orquestração de contêiner.

Se você estiver implantando em AKS (Serviço de Kubernetes do Azure), configurando ambientes de desenvolvimento ou configurando cargas de trabalho de produção, essa referência abrange padrões de configuração, tipos de credenciais e variáveis de ambiente necessários para proteger seus aplicativos com Microsoft Entra ID.

Visão geral da configuração

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

• Variáveis de ambiente (recomendadas para Kubernetes)
• Entra ID configuração – appsettings.json arquivo anexado ao contêiner ou inserido no arquivo yaml.
• Argumentos de linha de comando
• Configuração de Aplicativos do Azure ou Key Vault (para cenários avançados)

Configurações de Entra ID principais

Microsoft Entra SDK para implantações de ID do Agente exigem configurações de Entra ID principais para autenticar tokens de entrada e adquirir tokens para APIs downstream. 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, defina as principais configurações de Entra ID do SDK para autenticar tokens de entrada e adquirir tokens para APIs downstream.

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 SDK Microsoft Entra para ID do Agente dá suporte a vários tipos de credencial de cliente para autenticação com Microsoft Entra ID ao adquirir tokens para APIs downstream. Escolha o tipo de credencial que melhor se ajusta ao ambiente de implantação e aos requisitos de segurança e verifique se a configuração escolhida é apropriada para seu cenário.

Cada tipo de credencial atende a cenários diferentes:

• Segredo do cliente: configuração simples para desenvolvimento e teste (não recomendado para produção)
• Key Vault Certificate: ambientes de produção com gerenciamento centralizado de certificados
• Certificado de Arquivo: quando os certificados são montados como arquivos (por exemplo, por meio de segredos do Kubernetes)
• Certificate Store: ambientes Windows com repositórios de certificados
• Workload Identity for Containers: recomendado para AKS, usando ID de carga de trabalho do Microsoft Entra com projeção de token baseada em arquivo
• Managed Identity for VMs/App Services: Máquinas Virtuais do Azure e Serviços de Aplicativo com identidades gerenciadas atribuídas pelo sistema ou pelo usuário (não para contêineres)

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

Segredo do cliente

Essa configuração configura Entra ID autenticação usando um segredo do cliente 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 de Key Vault

Essa configuração configura Entra ID autenticação usando um certificado armazenado em 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>"

Certificado do arquivo

Essa configuração configura Entra ID autenticação usando um certificado armazenado como um arquivo.

- 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 do repositório

Essa configuração configura Entra ID autenticação usando um certificado do repositório de certificados local.

- 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)

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

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Note: o caminho do arquivo de token /var/run/secrets/azure/tokens/azure-identity-token ou uma variável de ambiente é projetado automaticamente pelo webhook de Identidade da Carga de Trabalho Azure quando o pod está configurado corretamente com a anotação da conta de serviço e o rótulo do pod. Consulte Usando a Identidade Gerenciada para obter instruções de instalação completas.

Identidade Gerenciada para VMs e Serviços de Aplicativo

Para cenários clássicos de identidade gerenciada Azure em Máquinas Virtuais ou Serviços de Aplicativo (não em contêineres), 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 o AKS, use SignedAssertionFilePath conforme mostrado acima. Para Kubernetes e Docker, use certificados de cliente. Para obter detalhes, consulte https://aka.ms/idweb/client-credentials

Recursos adicionais

Para obter detalhes completos sobre todas as opções de configuração de credencial 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 prioridade:

# 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 SDK Microsoft Entra para ID do Agente avalia as credenciais em ordem numérica (0, 1, 2 etc.) e usa a primeira credencial que é autenticada com êxito.

Configuração de APIs downstream

Configure APIs downstream que seu aplicativo precisa chamar usando fluxos de token OBO (em nome). O SDK Microsoft Entra para ID do Agente gerencia a aquisição de token e fornece cabeçalhos de autenticação para essas 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 à API do 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 token

Ajustar o comportamento de aquisição de token:

- 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 solicitação HTTP assinada (SHR)

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

- 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

Configurar 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"

configurações de ASP.NET Core

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

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

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 do 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 exigir AgentIdentity
• AgentUsername e AgentUserId são mutuamente exclusivos

Consulte Identidades do Agente para obter semântica detalhada.

Exemplo de configuração completa

O exemplo a seguir fornece um exemplo pronto para produção mostrando como implantar o SDK com a 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 de credenciais com segurança em Segredos 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 efetivo de diferentes ambientes, mantendo a segurança.

Kubernetes ConfigMap

O ConfigMap armazena configurações não confidenciais para o SDK, incluindo configurações de Entra ID, APIs downstream e níveis de log.

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 Segredo armazena credenciais confidenciais, como segredos do 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 Segredo no contêiner do SDK, garantindo que a configuração e as credenciais sejam 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

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

Desenvolvimento

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

De preparo

- 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 SDK do Microsoft Entra para ID do Agente valida a configuração na inicialização e registra erros para:

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

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

kubectl logs <pod-name> -c sidecar

Práticas recomendadas

1. Use Segredos para Credenciais: armazene segredos e certificados do cliente em Segredos do Kubernetes ou Azure Key Vault. Consulte também https://aka.ms/msidweb/client-credentials
2. Configuração separada por ambiente: use ConfigMaps para gerenciar configurações específicas do ambiente
3. Habilitar o registro em log apropriado: usar o log de depuração no desenvolvimento, Informações/Aviso em 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 a Identidade de Carga de Trabalho para Contêineres: para implantações em contêineres (AKS), prefira ID de carga de trabalho do Microsoft Entra com SignedAssertionFilePath em vez de segredos do cliente para segurança aprimorada
6. Use Managed Identity for VMs/App Services: para Azure VMs e Serviços de Aplicativo, use identidades gerenciadas atribuídas pelo sistema ou pelo usuário
7. Validar em Tempo de Implantação: Testar a configuração no preparo antes da implantação de produção

Conteúdo relacionado

• Identidades do agente
• Referência de pontos de extremidade
• Práticas recomendadas de segurança
• Solução de problemas