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

Este guia fornece opções de configuração para o SDK de Autenticação Microsoft Entra ID (sidecar), 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 de Autenticação Microsoft Entra ID (sidecar) é configurado usando fontes de configuração após ASP.NET Core convenções. 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 ID implantações do SDK de Autenticação (sidecar) exigem configurações principais de Entra ID 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 de Autenticação Microsoft Entra ID (sidecar) 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:

Escolher uma credencial por ambiente

Selecione a credencial com base em onde o sidecar é executado. Ambas SignedAssertionFilePath e SignedAssertionFromManagedIdentity as credenciais de identidade federadas (FIC). Eles diferem em como o sidecar obtém a declaração assinada.

Importante: SignedAssertionFromManagedIdentity não é uma credencial do Kubernetes de uso geral e não é um fallback para SignedAssertionFilePath. Ele usa Azure Identidade Gerenciada e investiga Azure ambientes de hospedagem, como Fabric de Serviço, Serviço de Aplicativo e IMDS. Em um host não Azure, ele não encontra nenhum deles e a solicitação eventualmente atinge o tempo limite no IMDS. Se o sidecar atingir inesperadamente o IMDS, você selecionou esse tipo de origem. Use SignedAssertionFilePath em seu lugar.

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

Essa configuração configura Entra ID autenticação usando ID de carga de trabalho do Microsoft Entra no AKS. Essa é a abordagem recomendada no AKS porque o Azure projetos de webhook de Identidade de Carga de Trabalho e gira o token para você.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Observação: no AKS, o caminho /var/run/secrets/azure/tokens/azure-identity-token do arquivo de token ou uma variável de ambiente é projetado automaticamente pelo webhook Azure Workload Identity 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 da carga de trabalho para Kubernetes não Azure ou locais

O fluxo de Identidade do Agente não está limitado ao AKS. Qualquer plataforma do Kubernetes, incluindo o local e outras nuvens, pode usar SignedAssertionFilePath com a federação de identidade de carga de trabalho. Como não há nenhum webhook de identidade de carga de trabalho Azure fora do AKS, você aponta o sidecar para o token de conta de serviço projetado que 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 arquivo em cada solicitação de token, portanto, a rotação controlada pela plataforma da declaração projetada é suportada automaticamente.

Para usar essa credencial no Kubernetes não Azure, seu ambiente deve atender a estes pré-requisitos:

• Sua plataforma kubernetes projeta um token de conta de serviço no pod sidecar, por exemplo, por meio de um volume projetado serviceAccountToken .
• O cluster expõe um emissor OIDC publicamente acessível e um ponto de extremidade JWKS para que Microsoft Entra possam validar a declaração.
• Uma FIC (credencial de identidade federada) é configurada no aplicativo Blueprint, com o emissor e o assunto que correspondem ao token projetado.

Se sua plataforma não puder fornecer um token OIDC projetado ou um emissor público, use uma credencial de certificado, como Certificado de Key Vault ou Certificado do arquivo.

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 em ambientes não Azure ou locais. Ele usa Azure Identidade Gerenciada por meio do IMDS e funciona apenas em Azure computação que fornece identidade gerenciada. Em um host não Azure, ele investiga Azure pontos de extremidade de hospedagem e, em seguida, atinge o tempo limite no IMDS, que pode parecer com o SDK sendo codificado para IMDS. Para Kubernetes em qualquer lugar, incluindo o 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 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 de Autenticação Microsoft Entra ID (sidecar) 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 de Autenticação Microsoft Entra ID (sidecar) 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 de Autenticação Microsoft Entra ID (sidecar) 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

Solução de problemas de credenciais

Solicitações chegam inesperadamente ao IMDS ou atingem o tempo limite

Sintoma: o sidecar trava ou atinge o tempo limite ao adquirir um token downstream e os logs mostram solicitações para o ponto de extremidade do IMDS (169.254.169.254), mesmo em um host não Azure.

Causa: a credencial está configurada como SignedAssertionFromManagedIdentity. Esse tipo de origem investiga intencionalmente Azure ambientes de hospedagem e IMDS, que não existem fora Azure. Essa é uma opção de configuração, não um fallback de SignedAssertionFilePath.

Solução:

1. Confirme se o efetivo SourceType é SignedAssertionFilePath, não SignedAssertionFromManagedIdentity.
2. Verifique se nenhuma variável de ambiente ou ConfigMap substitui as reintroduções SignedAssertionFromManagedIdentity.
3. Verifique se isso SignedAssertionFileDiskPath aponta para o token projetado montado no contêiner sidecar.
4. No Kubernetes não Azure, confirme se o emissor do OIDC do cluster e o JWKS são acessíveis publicamente e se existe um FIC correspondente no aplicativo Blueprint.

Quando você relatar um problema persistente, capture a versão do sidecar, a configuração de runtime efetiva e os logs de contêiner de uma solicitação com falha.

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