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

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 a autenticação da ID do Microsoft Entra, 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 no 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 credencial e variáveis de ambiente necessárias para proteger seus aplicativos com a ID do Microsoft Entra.

Visão geral da configuração

O SDK do Microsoft Entra para AgentID é configurado usando fontes de configuração após as convenções do 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)
• Configuração da ID do Entra – appsettings.json arquivo anexado ao contêiner ou inserido no arquivo yaml.
• Argumentos de linha de comando
• Configuração de Aplicativo do Azure ou Key Vault (para cenários avançados)

Configurações da ID do Core Entra

O SDK do Microsoft Entra para implantações agentID exige as principais configurações de ID do Entra 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 ID do Entra para o 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 do Microsoft Entra para AgentID dá suporte a vários tipos de credencial de cliente para autenticação com a ID do Microsoft Entra 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)
• Certificado do Key Vault: 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)
• Repositório de Certificados: ambientes do Windows com repositórios de certificados
• Identidade de carga de trabalho para contêineres: recomendado para AKS, usando a Identidade de Carga de Trabalho do Azure AD com projeção de token baseada em arquivo
• Identidade Gerenciada para VMs/Serviços de Aplicativo: 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 de Cliente

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

Essa configuração configura a autenticação de ID do Entra 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>"

Certificado do arquivo

Essa configuração configura a autenticação de ID do Entra 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 a autenticação de ID do Entra 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 a autenticação de ID do Entra usando a Identidade de Carga de Trabalho do Azure AD 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"

Observação: o caminho /var/run/secrets/azure/tokens/azure-identity-token do arquivo de token ou uma variável de ambiente é projetado automaticamente pelo webhook de Identidade da Carga de Trabalho do Azure quando o pod está configurado corretamente com a anotação da conta de serviço e o rótulo de 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 do Azure em Máquinas Virtuais ou Serviços de Aplicativo (não 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 do Microsoft Entra para AgentID 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 do Microsoft Entra para AgentID 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 do 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 ID do Entra, 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 AgentID 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. Usar segredos para credenciais: armazene segredos e certificados do cliente nos Segredos do Kubernetes ou no 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. Usar a Identidade de Carga de Trabalho para Contêineres: para implantações em contêineres (AKS), prefira a Identidade de Carga de Trabalho do Azure AD em SignedAssertionFilePath vez de segredos do cliente para segurança aprimorada
6. Usar a Identidade Gerenciada para VMs/Serviços de Aplicativo: para VMs do Azure e Serviços de Aplicativo, use identidades gerenciadas atribuídas pelo usuário ou sistema
7. Validar em Tempo de Implantação: Testar a configuração no preparo antes da implantação de produção

Consulte Também

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