Referência de configuração: Definições do Microsoft Entra ID Auth SDK (sidecar)

Este guia fornece opções de configuração para o Microsoft Entra ID Auth SDK (sidecar), um serviço de autenticação containerizada que gere a 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 ID Auth SDK (sidecar) é configurado usando fontes de configuração seguindo as convenções do 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

As implementações do Microsoft Entra ID Auth SDK (sidecar) requerem definições centrais do Entra ID para autenticar tokens recebidos e adquirir tokens para APIs a jusante. 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 ID Auth SDK (sidecar) 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:

Escolha uma credencial por ambiente

Selecione a credencial com base na localização do sidecar. Ambos SignedAssertionFilePath e SignedAssertionFromManagedIdentity são credenciais de identidade federada (FIC). Diferem na forma como o sidecar obtém a afirmação assinada.

Importante: SignedAssertionFromManagedIdentity não é uma credencial Kubernetes de uso geral, nem é um recurso B para SignedAssertionFilePath. Utiliza o Azure Managed Identity e sonda ambientes de alojamento Azure como Service Fabric, App Service e IMDS. Num host que não seja Azure, não encontra nenhum destes casos, e o pedido acaba por expirar no IMDS. Se o seu sidecar chegar inesperadamente ao IMDS, selecionou este tipo de fonte. Utilize SignedAssertionFilePath em substituição.

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 no AKS (recomendado para AKS)

Esta configuração configura a autenticação do Entra ID usando o ID de carga de trabalho Microsoft Entra no AKS. Esta é a abordagem recomendada no AKS porque o webhook Azure Workload Identity projeta e roda o token para si.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Nota: No AKS, o caminho /var/run/secrets/azure/tokens/azure-identity-token do ficheiro token ou uma variável de ambiente é automaticamente projetado 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.

Workload Identity for non-Azure ou on-premises Kubernetes

O fluxo de Identidade do Agente não se limita ao AKS. Qualquer plataforma Kubernetes, incluindo on-premises e outras clouds, pode ser usada SignedAssertionFilePath com federação de identidade de carga de trabalho. Como não existe um webhook do Azure Workload Identity fora do AKS, aponta o sidecar para o token projetado da conta de serviço que a sua plataforma monta.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"
- name: AzureAd__ClientCredentials__0__SignedAssertionFileDiskPath
  value: "/var/run/secrets/tokens/sa-token"

O sidecar relê o ficheiro em cada pedido de token, pelo que a rotação orientada pela plataforma da asserção projetada é suportada automaticamente.

Para usar esta credencial no Kubernetes que não seja Azure, o seu ambiente deve cumprir estes pré-requisitos:

• A sua plataforma Kubernetes projeta um token de conta de serviço no sidecar pod, por exemplo, através de um volume projetado serviceAccountToken .
• O cluster expõe um emissor OIDC acessível publicamente e um endpoint JWKS para que a Microsoft Entra possa validar a afirmação.
• Uma credencial de identidade federada (FIC) é configurada na aplicação Blueprint, com o emissor e o sujeito que correspondem ao token projetado.

Se a sua plataforma não conseguir fornecer um token OIDC projetado ou um emissor público, use uma credencial de certificado como Certificate from Key Vault ou Certificate from File.

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 em ambientes que não sejam Azure ou on-premises. Utiliza o Azure Managed Identity através do IMDS e funciona apenas no Azure compute que fornece identidade gerida. Num host que não seja Azure, sonda os endpoints de hospedagem do Azure e depois expira no IMDS, o que pode parecer que o SDK está a ser codificado diretamente no IMDS. Para Kubernetes em qualquer lugar, incluindo AKS, use SignedAssertionFilePath. 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 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 ID Auth SDK (sidecar) 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 ID Auth SDK (sidecar) 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 ID Auth SDK (sidecar) 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

Credenciais de resolução de problemas

Pedidos chegam inesperadamente ao IMDS ou fazem um tempo de espera

Sintoma: O sidecar bloqueia ou expira ao adquirir um token a jusante, e os registos mostram pedidos para o endpoint IMDS (169.254.169.254), mesmo num host que não seja Azure.

Causa: A credencial está configurada como SignedAssertionFromManagedIdentity. Esse tipo de fonte sonda intencionalmente os ambientes de alojamento do Azure e o IMDS, que não existem fora do Azure. Isto é uma escolha de configuração, não um plano B de SignedAssertionFilePath.

Resolução:

1. Confirme que o efetivo SourceType é SignedAssertionFilePath, não SignedAssertionFromManagedIdentity.
2. Verifique se nenhuma variável de ambiente ou o override do ConfigMap reintroduz SignedAssertionFromManagedIdentity.
3. Verifica se isso SignedAssertionFileDiskPath aponta para o token projetado que está montado no contentor do sidecar.
4. No Kubernetes não Azure, confirme que o emissor OIDC do cluster e o JWKS são publicamente acessíveis e que existe um FIC correspondente na aplicação Blueprint.

Quando reportar um problema persistente, capture a versão sidecar, a configuração efetiva em tempo de execução e os registos do contentor de um pedido falhado.

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