Informations de référence sur la configuration : Microsoft Entra SDK pour les paramètres d’ID d’agent

Ce guide fournit des options de configuration pour le sdk Microsoft Entra pour AgentID, 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 sdk Microsoft Entra pour l’ID de l’agent est configuré à l’aide de sources de configuration suivantes ASP.NET Core conventions. 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 SDK pour les déploiements d’ID d’agent 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 sdk Microsoft Entra pour l’ID d’agent 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 :

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 pour les conteneurs (recommandé pour AKS)

Cette configuration configure l’authentification Entra ID à l’aide de ID de charge de travail Microsoft Entra pour les déploiements en conteneur (AKS). Il s’agit de l’approche recommandée pour les scénarios basés sur des conteneurs, car elle utilise la projection de jetons basée sur des fichiers.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Note : le chemin d’accès au fichier de jeton /var/run/secrets/azure/tokens/azure-identity-token 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é 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 : ne pas utiliser SignedAssertionFromManagedIdentity pour les environnements conteneurisés (Kubernetes, AKS, Docker). Pour AKS, utilisez SignedAssertionFilePath comme indiqué ci-dessus. Pour Kubernetes et Docker, utilisez des certificats clients. Pour plus d’informations, 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 sdk Microsoft Entra pour l’ID d’agent é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 Microsoft Entra pour l’ID d’agent 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

Le sdk Microsoft Entra pour l’ID de l’agent 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

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