Utilisez des secrets clients avec Microsoft. Identity.Web

Une clé secrète client est une valeur de chaîne utilisée par votre application pour prouver son identité lors de la demande de jetons à partir du Plateforme d'identités Microsoft. Microsoft. Identity.Web prend en charge les secrets client comme l’un des types d’informations d’identification pour les applications clientes confidentielles.

Choisir un type d'identifiants

Les applications clientes confidentielles ont besoin d’informations d’identification pour s’authentifier auprès du Plateforme d'identités Microsoft. Microsoft. Identity.Web prend en charge les types d’informations d’identification suivants via la section de configuration ClientCredentials :

Les secrets client sont des chaînes simples inscrites auprès de votre application dans Microsoft Entra ID. Bien qu’ils soient le type d’informations d’identification le plus simple à configurer, ils ont également des limitations de sécurité significatives :

• Elles peuvent être exposées accidentellement dans le code source, les logs ou les fichiers de configuration.
• Ils ont une date d’expiration et doivent être pivotés manuellement.
• Ils ne fournissent aucune preuve de chiffrement de l’identité de l’appelant au-delà de la possession du secret.

Configurer une clé secrète client dans appsettings.json

Pour configurer une clé secrète client, ajoutez un ClientCredentials array à la section AzureAd de votre fichier appsettings.json :

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

Le ClientCredentials tableau prend en charge plusieurs entrées. Microsoft.Identity.Web essaie chaque identifiant dans l’ordre jusqu’à ce qu’il réussisse, ce qui est utile pour les scénarios de rotation des secrets.

Stocker des secrets pour le développement

Cette section explique comment conserver les valeurs secrètes hors de votre code source pendant le développement local.

.NET Secret utilisateur

L’approche recommandée pour le stockage des secrets pendant le développement local est l’outil Gestionnaire de secrets. Les secrets utilisateur stockent des données sensibles en dehors du répertoire de votre projet, ce qui empêche les commits accidentels dans le contrôle de code source.

1. Initialisez les secrets utilisateur pour votre projet :

   dotnet user-secrets init
   

2. Définissez la valeur du secret client :

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. Vérifiez que le secret a été stocké :

   dotnet user-secrets list
   

Les secrets utilisateur sont automatiquement chargés dans l’environnement Development lorsque vous utilisez WebApplication.CreateBuilder() ou Host.CreateDefaultBuilder().

Votre appsettings.json doit contenir la structure sans la valeur secrète réelle :

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

Variables d'environnement

Vous pouvez également utiliser des variables d’environnement pour fournir la clé secrète client. .NET configuration mappe automatiquement les variables d’environnement qui utilisent le séparateur __ (trait de soulignement double) à la hiérarchie de configuration. Définissez la variable pour votre interpréteur de commandes :

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Les variables d’environnement sont prioritaires sur les valeurs dans appsettings.json, de sorte que la valeur secrète de votre fichier de configuration peut être vide ou omise.

Stocker des secrets pour des environnements avancés

Pour la préproduction, l’assurance qualité ou tout environnement partagé, utilisez Azure Key Vault en tant que source de configuration. Cette approche exclut les secrets des fichiers de configuration et des variables d’environnement tout en fournissant des fonctionnalités d’audit, de politiques d’accès et de rotation automatique.

Ajouter Azure Key Vault en tant que source de configuration

1. Installez le package NuGet requis :

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. Stockez la clé secrète client dans Azure Key Vault avec un nom mappé au chemin de configuration. Utilisez -- (tiret double) comme séparateur :

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Ajoutez Key Vault en tant que source de configuration dans Program.cs. Le code suivant inscrit Key Vault afin que ses secrets soient disponibles via l’API de configuration standard :

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

Le nom du secret Key Vault AzureAd--ClientCredentials--0--ClientSecret est mappé automatiquement au chemin de configuration AzureAd:ClientCredentials:0:ClientSecret.

Créer une clé secrète client dans le portail Azure

Procédez comme suit pour inscrire une clé secrète client pour votre application dans Microsoft Entra ID :

1. Connectez-vous au centre d’administration Microsoft Entra.
2. Accédez à Identity>Applications>inscriptions d'applications.
3. Dans la liste, sélectionnez votre application.
4. Dans le menu de gauche, sélectionnez Certificats et secrets.
5. Sélectionnez l’onglet Secrets client .
6. Sélectionnez Nouveau secret client.
7. Dans le volet Ajouter un secret client :
   • Entrez une description pour le secret (par exemple, « Secret de développement »).
   • Sélectionnez une durée d’expiration . Les options disponibles incluent 180 jours, 365 jours, 730 jours ou une date personnalisée.
   • Cliquez sur Ajouter.
8. Copiez immédiatement la valeur secrète. La valeur n’est affichée qu’une seule fois et ne peut pas être récupérée une fois que vous êtes éloigné de la page.

Gérer l’expiration et la rotation des secrets

Les secrets clients ont une durée de vie maximale et expirent à la date spécifiée lors de la création. Planifiez la rotation des secrets pour éviter les pannes d’application.

Surveiller l’expiration

• Vérifiez la colonne Expire dans la page Certificats et secrets de l’inscription de votre application.
• Configurez Microsoft Entra recommandations pour recevoir des alertes avant l’expiration des informations d’identification.

Stratégie de rotation

Utilisez le tableau ClientCredentials pour permettre une rotation sans interruption.

1. Créez un secret client dans le portail Azure.

2. Ajoutez le nouveau secret en tant qu’entrée supplémentaire dans le ClientCredentials tableau. Placez d’abord le nouveau secret pour qu’il soit essayé avant l’ancien :

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. Déployez la configuration mise à jour. Microsoft. Identity.Web tente les premières informations d’identification et revient au deuxième en cas d’échec du premier.

4. Après avoir confirmé que le nouveau secret fonctionne, supprimez l’ancien secret de la configuration et du portail Azure.

Migrer vers des informations d’identification de production

Avant de déployer en production, migrez des secrets client vers un type d’informations d’identification plus sécurisé :

Authentification basée sur un certificat

Les certificats fournissent une preuve de chiffrement d’identité et sont le type d’informations d’identification recommandé pour la production. La configuration suivante récupère un certificat à partir de Key Vault :

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Pour obtenir des instructions détaillées, consultez Utiliser des certificats avec Microsoft. Identity.Web.

Identité managée (sans certificat)

Pour les applications hébergées dans Azure, les identités managées éliminent la nécessité de gérer entièrement les informations d’identification. La configuration suivante utilise une identité managée affectée par l’utilisateur :

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

Pour obtenir des instructions détaillées, consultez Authentification sans certificat avec Microsoft. Identity.Web.

Liste des éléments à vérifier pour la migration

• [ ] Générez ou approvisionnez les nouvelles informations d’identification (certificat ou identité managée).
• [ ] Mettez à jour la configuration de votre application pour utiliser le nouveau type d’informations d’identification.
• [ ] Testez les nouvelles informations d’identification dans un environnement de test.
• [ ] Déployer en production.
• [ ] Supprimez l’ancien secret client du portail Azure.
• [ ] Vérifiez correctement les fonctions de l’application sans l’ancien secret.

Éviter les erreurs de sécurité courantes

Passez en revue les anti-modèles suivants et leurs alternatives recommandées lors de l’utilisation des secrets client :

Résoudre les erreurs courantes

Cette section traite des erreurs fréquentes que vous pouvez rencontrer lors de la configuration des secrets client.

Secret client non valide

Erreur:AADSTS7000215: Invalid client secret provided.

Causes possibles :

• La valeur secrète a été copiée de manière incorrecte. Les valeurs secrètes peuvent contenir des caractères spéciaux qui sont tronqués pendant les opérations de copie/collage.
• Le secret a été créé pour une inscription d’application différente de celle configurée dans ClientId.
• Le chemin de configuration est incorrect et la valeur secrète n’est pas lue par l’application.

Résolution :

1. Créez une clé secrète client dans le portail Azure et copiez soigneusement la valeur complète.

2. Vérifiez que le ClientId et le TenantId dans votre configuration correspondent à l'inscription de l'application où le secret a été créé.

3. Ajoutez un point d’arrêt ou une instruction de journalisation pour vérifier que la configuration est chargée correctement :

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

Clé secrète client expirée

Erreur:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Résolution :

1. Accédez à l’inscription de l’application dans le centre d’administration Microsoft Entra.
2. Vérifiez la date d’expiration sous Certificats et secrets>secrets client.
3. Créez un secret et mettez à jour la configuration de votre application.
4. Supprimez le secret expiré du portail.

Secret introuvable dans la configuration

Symptôme : L’application génère un NullReferenceException ou échoue à s’authentifier, car la valeur secrète est null.

Causes possibles :

• Les secrets utilisateur ne sont pas initialisés pour le projet.
• Le nom de la variable d’environnement ne correspond pas au chemin de configuration attendu.
• Key Vault n'est pas configuré en tant que source de configuration.
• L’application s’exécute dans un environnement non de développement où les secrets utilisateur ne sont pas chargés.

Résolution :

1. Vérifiez que les secrets utilisateur sont initialisés en vérifiant la présence d'un UserSecretsId dans votre fichier .csproj.
2. Vérifiez que le secret est défini en exécutant dotnet user-secrets list.
3. Vérifiez que le chemin de configuration correspond exactement à : AzureAd:ClientCredentials:0:ClientSecret.
4. Si vous exécutez en dehors de l’environnement de développement, vérifiez que la source de configuration appropriée (variable d’environnement ou Key Vault) est disponible.

Contenu connexe

• Certificats avec Microsoft.Identity.Web
• Authentification sans certificat
• Vue d’ensemble du cache de jetons
• Stockage sécurisé des secrets d’application dans le développement dans ASP.NET Core
• fournisseur de configuration Azure Key Vault dans ASP.NET Core