Informations de référence sur la configuration : paramètres du Kit de développement logiciel (SDK) d’authentification (sidecar) Microsoft Entra ID

Ce guide fournit des options de configuration pour le sdk Microsoft Entra ID Auth (sidecar), un service d’authentification conteneurisé qui gère l’acquisition et la gestion des jetons pour les applications dans des environnements conteneurisés. Le SDK simplifie l’intégration des identités en gérant Microsoft Entra ID l’authentification, les flux de jetons au nom de (OBO) et les appels d’API en aval sans que les applications n’incorporent directement des bibliothèques d’authentification.

Bien que ce guide se concentre sur les modèles de déploiement Kubernetes, le SDK peut être déployé dans n’importe quel environnement conteneurisé, y compris Docker, Azure Container Instances et d’autres plateformes d’orchestration de conteneurs.

Si vous effectuez un déploiement sur Azure Kubernetes Service (AKS), la configuration d'environnements de développement ou la configuration des charges de travail de production, cette référence couvre les modèles de configuration, les types d'informations d'identification et les variables d'environnement nécessaires pour sécuriser vos applications avec Microsoft Entra ID.

Vue d’ensemble de la configuration

Le kit SDK d’Microsoft Entra ID Auth (sidecar) est configuré à l’aide de sources de configuration en suivant les conventions de ASP.NET Core. Les valeurs de configuration peuvent être fournies via plusieurs méthodes, notamment :

• Variables d’environnement (recommandées pour Kubernetes)
• configuration Entra ID - fichier appsettings.json attaché au conteneur ou incorporé dans le fichier yaml.
• Arguments de ligne de commande
• Azure App Configuration ou Key Vault (pour les scénarios avancés)

Paramètres de Entra ID de base

Microsoft Entra ID déploiements du SDK Auth (sidecar) nécessitent des paramètres de Entra ID principaux pour authentifier les jetons entrants et acquérir des jetons pour les API en aval. Utilisez les informations d’identification du client appropriées au format YAML suivant, généralement en tant que variables d’environnement, pour garantir l’authentification sécurisée.

Configuration requise

Tout d’abord, configurez les paramètres de Entra ID de base du KIT de développement logiciel (SDK) pour authentifier les jetons entrants et acquérir des jetons pour les API en aval.

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

Configuration des informations d’identification du client

Le kit SDK Microsoft Entra ID Auth (sidecar) prend en charge plusieurs types d’informations d’identification client pour l’authentification avec Microsoft Entra ID lors de l’acquisition de jetons pour les API en aval. Choisissez le type d’informations d’identification qui convient le mieux à votre environnement de déploiement et aux exigences de sécurité, puis vérifiez que la configuration que vous choisissez convient à votre scénario.

Chaque type d’informations d’identification répond à différents scénarios :

• Clé secrète client : configuration simple pour le développement et le test (non recommandé pour la production)
• Key Vault Certificat : Environnements de production avec gestion centralisée des certificats
• Certificat de fichier : quand les certificats sont montés en tant que fichiers (par exemple, via des secrets Kubernetes)
• Certificate Store : environnements Windows avec des magasins de certificats
• Workload Identity for Containers : recommandé pour AKS, à l’aide de ID de charge de travail Microsoft Entra avec une projection de jetons basée sur des fichiers
• Identité managée pour les machines virtuelles/App Services : Machines virtuelles Azure et App Services avec des identités managées système ou affectées par l’utilisateur (et non pour les conteneurs)

Configurez une ou plusieurs sources d’informations d’identification au format YAML suivant :

Choisir des informations d’identification par environnement

Sélectionnez les informations d’identification en fonction de l’emplacement d’exécution du side-car. Les deux SignedAssertionFilePath et SignedAssertionFromManagedIdentity sont des informations d’identification d’identité fédérée (FIC). Ils diffèrent dans la façon dont le side-car obtient l’assertion signée.

Important : SignedAssertionFromManagedIdentity n’est pas des informations d’identification Kubernetes à usage général, et ce n’est pas un secours pour SignedAssertionFilePath. Il utilise Azure Identité managée et sondes Azure environnements d’hébergement tels que Service Fabric, App Service et IMDS. Sur un hôte non Azure, il ne trouve aucun de ces éléments, et la requête expire finalement sur IMDS. Si votre side-car atteint de façon inattendue IMDS, vous avez sélectionné ce type de source. Utilisez SignedAssertionFilePath à la place.

Secret de client

Cette configuration configure Entra ID l’authentification à l’aide d’une clé secrète client pour l’authentification de service à service.

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

Certificat de Key Vault

Cette configuration configure l’authentification Entra ID à l’aide d’un certificat stocké dans 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>"

Certificat à partir d’un fichier

Cette configuration configure Entra ID l’authentification à l’aide d’un certificat stocké en tant que fichier.

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

Certificat à partir du magasin

Cette configuration configure Entra ID l’authentification à l’aide d’un certificat à partir du magasin de certificats local.

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

Identité de charge de travail sur AKS (recommandé pour AKS)

Cette configuration configure l’authentification Entra ID à l’aide de ID de charge de travail Microsoft Entra sur AKS. Il s’agit de l’approche recommandée sur AKS, car les projets webhook d’identité de charge de travail Azure et font pivoter le jeton pour vous.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Remarque : Sur AKS, le chemin /var/run/secrets/azure/tokens/azure-identity-token du fichier de jeton ou une variable d’environnement est automatiquement projeté par le webhook d’identité de charge de travail Azure lorsque votre pod est correctement configuré avec l’annotation de compte de service et l’étiquette de pod. Pour obtenir des instructions d’installation complètes, consultez Utilisation de l’identité managée .

Identité de charge de travail pour les Azure ou Kubernetes locaux

Le flux d’identité de l’agent n’est pas limité à AKS. Toute plateforme Kubernetes, y compris localement et d’autres clouds, peut être utilisée SignedAssertionFilePath avec la fédération des identités de charge de travail. Étant donné qu'il n'existe aucun Azure webhook d'identité de charge de travail en dehors d'AKS, vous pointez le side-car sur le jeton de compte de service projeté que votre plateforme monte.

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

Le sidecar réexécure le fichier sur chaque demande de jeton, de sorte que la rotation pilotée par la plateforme de l’assertion projetée est prise en charge automatiquement.

Pour utiliser ces informations d’identification sur kubernetes non Azure, votre environnement doit respecter les conditions préalables suivantes :

• Votre plateforme Kubernetes projette un jeton de compte de service dans le pod sidecar, par exemple via un volume projeté serviceAccountToken .
• Le cluster expose un émetteur OIDC accessible publiquement et un point de terminaison JWKS afin que Microsoft Entra puissent valider l’assertion.
• Les informations d’identification d’identité fédérée (FIC) sont configurées sur l’application Blueprint, avec l’émetteur et l’objet qui correspondent au jeton projeté.

Si votre plateforme ne peut pas fournir un jeton OIDC projeté ou un émetteur public, utilisez plutôt des informations d'identification de certificat telles que le certificat de Key Vault ou le certificat à partir d'un fichier.

Identité managée pour les machines virtuelles et App Services

Pour les scénarios d’identité managée Azure classiques sur Machines Virtuelles ou App Services (et non sur les conteneurs), utilisez SignedAssertionFromManagedIdentity :

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

Important : n’utilisez SignedAssertionFromManagedIdentity pas dans des environnements non Azure ou locaux. Il utilise Azure identité managée via IMDS et fonctionne uniquement sur Azure calcul qui fournit une identité managée. Sur un hôte non Azure, il sonde Azure points de terminaison d’hébergement, puis expire sur IMDS, ce qui peut ressembler au KIT de développement logiciel (SDK) encodé en dur vers IMDS. Pour Kubernetes n’importe où, y compris AKS, utilisez SignedAssertionFilePath. Pour en savoir plus, consultez https://aka.ms/idweb/client-credentials

Ressources additionnelles

Pour plus d’informations sur toutes les options de configuration des informations d’identification et leur utilisation, consultez la spécification CredentialDescription dans le référentiel microsoft-identity-abstractions-for-dotnet.

Priorité des informations d’identification

Configurez plusieurs informations d’identification avec une sélection basée sur la priorité :

# 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

Le kit SDK d’Microsoft Entra ID Auth (sidecar) évalue les informations d’identification dans l’ordre numérique (0, 1, 2, etc.) et utilise les premières informations d’identification qui s’authentifient correctement.

Configuration des API en aval

Configurez les API en aval que votre application doit appeler à l’aide de flux de jetons OBO (on-behalf-of). Le sdk d’Microsoft Entra ID Auth (sidecar) gère l’acquisition de jetons et fournit des en-têtes d’authentification pour ces appels d’API. Chaque API en aval nécessite un nom de configuration unique et des paramètres spécifiques pour l’acquisition de jetons et la gestion des requêtes HTTP.

Définissez chaque API en aval avec son URL de base, ses étendues requises et ses paramètres facultatifs. Le Kit de développement logiciel (SDK) gère automatiquement l’acquisition de jetons à l’aide du jeton utilisateur entrant et fournit les en-têtes d’autorisation appropriés pour les appels d’API de votre application.

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

Options d’acquisition de jetons

Ajuster le comportement d’acquisition de jeton :

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

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

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

Configuration de la requête HTTP signée (SHR)

Activez les requêtes HTTP signées pour une sécurité renforcée :

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

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

Configuration de la journalisation

Configurer les niveaux de journalisation :

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

paramètres de ASP.NET Core

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

remplacements de configuration Per-Request

Tous les points de terminaison d’acquisition de jeton acceptent les paramètres de requête pour remplacer la configuration :

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

Remplacements d’identité de l’agent

Spécifiez l’identité de l’agent au moment de la demande :

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

Règles importantes :

• AgentUsername et AgentUserId exiger AgentIdentity
• AgentUsername et AgentUserId s’excluent mutuellement

Consultez Les identités de l’agent pour obtenir une sémantique détaillée.

Exemple de configuration complet

Voici un exemple prêt pour la production montrant comment déployer le Kit de développement logiciel (SDK) avec une séparation appropriée de la configuration et des secrets. Cet exemple illustre la configuration de plusieurs API en aval, à l’aide de Kubernetes ConfigMaps pour les paramètres non sensibles, le stockage sécurisé des informations d’identification dans les secrets et l’application de configurations spécifiques à l’environnement pour un déploiement sécurisé.

Ce modèle suit les bonnes pratiques Kubernetes en séparant les données de configuration des informations d’identification sensibles, ce qui permet une gestion efficace des différents environnements tout en conservant la sécurité.

Kubernetes ConfigMap

ConfigMap stocke les paramètres de configuration non sensibles pour le Kit de développement logiciel (SDK), notamment les paramètres de Entra ID, les API en aval et les niveaux de journalisation.

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"

Secret Kubernetes

Le secret stocke les informations d’identification sensibles, telles que les secrets client, séparément de ConfigMap.

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

Déploiement avec ConfigMap et secret

Le déploiement monte à la fois le ConfigMap et le secret dans le conteneur du Kit de développement logiciel (SDK), ce qui garantit que la configuration et les informations d’identification sont correctement séparées.

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

Configuration spécifique à l’environnement

Configurez les paramètres spécifiques à l’environnement pour adapter la sécurité, la journalisation et l’isolation des locataires pour vos environnements de déploiement. Chaque environnement nécessite différentes approches de configuration pour équilibrer l’efficacité du développement, la validation intermédiaire et les exigences de sécurité de production.

Développement

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

Production

- 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

La Microsoft Entra ID SDK Auth (sidecar) valide la configuration au démarrage et journalise les erreurs pour :

• Paramètres requis manquants (TenantId, ClientId)
• Configurations d’informations d’identification non valides
• Définitions d’API en aval mal formées
• Formats d’URL ou d’étendue non valides

Vérifiez les journaux de conteneur pour les messages de validation :

kubectl logs <pod-name> -c sidecar

Résolution des problèmes d’informations d’identification

Les demandes atteignent de façon inattendue IMDS ou expirent

Symptôme : le side-car bloque ou expire l’acquisition d’un jeton en aval, et les journaux affichent les demandes au point de terminaison IMDS (169.254.169.254), même sur un hôte non Azure.

Cause : les informations d’identification sont configurées en tant que SignedAssertionFromManagedIdentity. Ce type de source sonde intentionnellement Azure environnements d'hébergement et IMDS, qui n'existent pas en dehors de Azure. Il s’agit d’un choix de configuration, pas d’un secours de SignedAssertionFilePath.

Résolution :

1. Vérifiez que l’effet SourceType est SignedAssertionFilePath, et non SignedAssertionFromManagedIdentity.
2. Vérifiez qu’aucune variable d’environnement ou configMap ne remplace les réintroduces SignedAssertionFromManagedIdentity.
3. Vérifiez que cela SignedAssertionFileDiskPath pointe vers le jeton projeté monté dans le conteneur sidecar.
4. Sur kubernetes non Azure, vérifiez que l'émetteur OIDC et le JWKS du cluster sont accessibles publiquement et qu'un FIC correspondant existe sur l'application Blueprint.

Lorsque vous signalez un problème persistant, capturez la version side-car, la configuration d’exécution effective et les journaux de conteneur à partir d’une requête défaillante.

Meilleures pratiques

1. Utilisez les secrets pour les informations d’identification : stockez les certificats et secrets client dans les secrets Kubernetes ou Azure Key Vault. Voir aussi https://aka.ms/msidweb/client-credentials
2. Configuration distincte par environnement : utiliser ConfigMaps pour gérer les paramètres spécifiques à l’environnement
3. Activer la journalisation appropriée : utiliser la journalisation de débogage dans le développement, informations/avertissements en production
4. Configurer les contrôles d’intégrité : vérifier que les points de terminaison de contrôle d’intégrité sont correctement configurés
5. Utiliser l’identité de charge de travail pour les conteneurs : pour les déploiements en conteneur (AKS), préférez ID de charge de travail Microsoft Entra avec SignedAssertionFilePath par rapport aux secrets clients pour une sécurité renforcée
6. Utiliser l’identité managée pour les machines virtuelles/App Services : pour Azure machines virtuelles et App Services, utilisez des identités managées affectées par le système ou l’utilisateur
7. Valider au moment du déploiement : tester la configuration en préproduction avant le déploiement de production

Contenu connexe

• Identités d’agent
• Informations de référence sur les points de terminaison
• Meilleures pratiques en matière de sécurité
• résolution des problèmes