Configurez le déchiffrement de jeton dans Microsoft. Identity.Web

Cet article explique comment configurer des certificats de déchiffrement de jeton dans Microsoft. Identity.Web afin que votre application puisse déchiffrer des jetons chiffrés à partir de la Plateforme d'identités Microsoft.

Par défaut, le Plateforme d'identités Microsoft émet des jetons (jetons d’ID, jetons SAML) en tant que JWT signés mais non chiffrés. Tout intermédiaire qui intercepte un jeton peut lire ses revendications. Pour les applications qui gèrent les revendications sensibles ou fonctionnent dans des environnements de conformité stricts, le Plateforme d'identités Microsoft prend en charge le chiffrement token. Lorsqu’elle est activée, la plateforme d’identité chiffre la charge utile du jeton à l’aide d’une clé publique inscrite auprès de votre application. Seule votre application, qui contient la clé privée correspondante, peut déchiffrer et lire le jeton.

Fonctionnement du chiffrement des jetons

1. Vous générez un certificat avec une paire de clés publique/privée.
2. Vous chargez la clé public (le fichier .cer) dans l’inscription de votre application dans Microsoft Entra ID.
3. Lorsque le Plateforme d'identités Microsoft émet un jeton pour votre application, il chiffre le jeton à l’aide de votre clé publique.
4. Votre application utilise la clé privée pour déchiffrer le jeton avant de traiter les revendications.

Le chiffrement utilise un schéma à deux couches : la charge utile du jeton est chiffrée avec une clé de chiffrement de contenu symétrique, qui est encapsulée (chiffrée) à l’aide de votre clé publique. Microsoft Entra prend en charge les algorithmes d’habillage de clé RSA-OAEP et RSA-OAEP-256.

Déterminer quand configurer le déchiffrement de jeton

Configurez le déchiffrement de jeton lorsque votre application répond à l’une des conditions suivantes :

• Reçoit des jetons SAML chiffrés : les applications d’entreprise qui utilisent l’authentification unique BASÉE sur SAML et nécessitent des assertions SAML chiffrées pour des raisons de conformité ou de réglementation.
• Reçoit des jetons d’ID chiffrés : les applications web qui optent pour le chiffrement des jetons d’ID afin de protéger les revendications sensibles (appartenances aux groupes, revendications personnalisées) d’être lues en transit.
• Fonctionne dans des environnements à haute sécurité : applications dans des scénarios gouvernementaux, financiers ou de santé où la confidentialité des jetons est imposée par la stratégie.

Respecter les conditions préalables

Avant de configurer le déchiffrement des jetons, vérifiez les exigences suivantes :

• An X.509 avec une clé privée — Vous avez besoin d’un certificat au format .pfx (PKCS#12) ou stocké dans un emplacement accessible à votre application (Azure Key Vault, magasin de certificats ou système de fichiers). La clé privée est requise pour déchiffrer les jetons.
• Inscription d'application configurée pour le chiffrement de jeton : chargez la clé publique du certificat dans votre inscription d'application dans Microsoft Entra ID. Consultez Enregistrer le certificat de déchiffrement plus loin dans cet article.
• Microsoft. Identity.Web 2.1.0 ou version ultérieure : la propriété de configuration TokenDecryptionCredentials est disponible dans Microsoft. Identity.Web 2.1.0 et versions ultérieures.

Configurer le déchiffrement de jeton dans appsettings.json

Microsoft. Identity.Web utilise le tableau TokenDecryptionCredentials dans votre section de configuration AzureAd. Ce tableau suit le même format de description des informations d’identification que ClientCredentials. Vous pouvez donc charger des certificats de déchiffrement à partir de Azure Key Vault, du magasin de certificats, d’un chemin d’accès de fichier ou d’une chaîne encodée en Base64.

Configurer une configuration de base

L’exemple suivant montre la configuration minimale pour charger un certificat de déchiffrement à partir de Azure Key Vault :

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc",

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

Aucun code supplémentaire n’est requis. Quand Microsoft. Identity.Web détecte la configuration TokenDecryptionCredentials, elle charge automatiquement le certificat spécifié et l’inscrit auprès du gestionnaire d’authentification OpenID Connect pour le déchiffrement de jeton.

Choisir une source de justificatifs

Le TokenDecryptionCredentials tableau prend en charge les mêmes types sources que ClientCredentials. Le tableau suivant récapitule chaque option :

Key Vault (recommandé pour la production)

La configuration suivante charge un certificat de déchiffrement à partir de Azure Key Vault :

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

L'identité managée ou le principal de service de votre application doivent disposer d'autorisations Get et List sur les certificats Key Vault.

Magasin de certificats (Windows)

La configuration suivante charge un certificat à partir du magasin de certificats Windows par empreinte numérique :

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Chemins d'accès au fichier

La configuration suivante charge un certificat à partir d’un .pfx fichier sur disque :

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Codé en base64

La configuration suivante charge un certificat à partir d’une chaîne encodée en Base64 :

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Cette option est utile lorsque vous injectez le certificat via une variable d’environnement ou un secret de pipeline CI/CD.

Configurer plusieurs certificats de déchiffrement

Vous pouvez spécifier plusieurs certificats dans le TokenDecryptionCredentials tableau. Microsoft. Identity.Web tente chaque certificat dans l’ordre jusqu’à ce qu’un déchiffre correctement le jeton. Cette fonctionnalité est essentielle pour la rotation des certificats (voir Rotation des certificats).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Inscrire le certificat de déchiffrement dans Microsoft Entra ID

Pour que la plateforme d'identité Microsoft chiffre les jetons de votre application, vous devez charger la clé publique du certificat dans votre enregistrement d'application :

1. Connectez-vous au centre d’administration Microsoft Entra.
2. Accédez à Identity>Applications>inscriptions d'applications et sélectionnez votre application.
3. Sélectionnez Certificats et secrets>Certificats>Charger un certificat.
4. Chargez le .cer fichier (clé publique uniquement) de votre certificat de déchiffrement.
5. Après le chargement, notez la valeur de l’empreinte numérique : elle doit correspondre au certificat que votre application utilise.

Activer le chiffrement de jeton pour l’application

Après avoir chargé le certificat, vous devez configurer votre application pour recevoir des jetons chiffrés. Cette configuration est actuellement disponible via microsoft API Graph ou PowerShell :

Utilisant Microsoft Graph PowerShell :

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Faire pivoter les certificats de déchiffrement

La rotation des certificats pour le déchiffrement de jeton nécessite une approche minutieuse et progressive pour éviter les temps d’arrêt :

Étapes de rotation

1. Générer un nouveau certificat : créez un certificat X.509 avec une clé privée.
2. Ajoutez le nouveau certificat à votre configuration d’application : ajoutez le nouveau certificat au TokenDecryptionCredentials tableau en même temps que le certificat existant. Placez le nouveau certificat en premier dans le tableau.
3. Uploader la nouvelle clé publique : chargez le fichier .cer du nouveau certificat dans l'inscription de votre application dans Microsoft Entra.
4. Déployez votre application : déployez la configuration mise à jour afin que votre application puisse déchiffrer des jetons avec l’un ou l’autre certificat.
5. Basculez la clé de chiffrement active : mettez à jour l'objet tokenEncryptionKeyId de l'application pour qu'il keyId pointe vers le nouveau certificat.
6. Vérifiez : vérifiez que votre application déchiffre correctement les jetons chiffrés avec le nouveau certificat.
7. Supprimez l’ancien certificat : après une période de grâce (au moins 24 heures pour autoriser l’expiration des jetons mis en cache), supprimez l’ancien certificat de l’inscription de votre application et de la configuration de votre application.

Configuration pendant la rotation

Pendant la fenêtre de rotation, votre TokenDecryptionCredentials devrait contenir les deux certificats :

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Résoudre les problèmes de déchiffrement des jetons

Utilisez les instructions suivantes pour diagnostiquer et résoudre les problèmes courants de déchiffrement des jetons.

Échecs de déchiffrement de jeton

Symptôme: Votre application lève ou retourne une SecurityTokenDecryptionFailedException erreur 401/500 lors du traitement des jetons.

Causes courantes :

Clé privée manquante

Symptôme:CryptographicException: The certificate key is not accessible ou InvalidOperationException: Certificate does not have a private key.

Causes et solutions :

• Certificat exporté sans clé privée : réexportez le certificat au .pfx format et assurez-vous d’inclure la clé privée pendant l’exportation.
• Key Vault stratégie d'accès — Lors de l'utilisation de Azure Key Vault, Vérifiez que l'identité de votre application dispose de l'autorisation Get sur les deux Certificates et Secrets. La clé privée est stockée en tant que secret dans Key Vault.
• Certificate store permissions : sur Windows, vérifiez que l’identité du pool d’applications ou le compte de service dispose d’un accès en lecture à la clé privée. Utilisez l’option Gérer les clés privées dans le magasin de certificats du composant logiciel enfichable MMC.

Incompatibilité de l’algorithme

Symptôme:SecurityTokenDecryptionFailedException avec un message indiquant un algorithme non pris en charge.

Causes et solutions :

• Type de clé non pris en charge : Microsoft Entra prend en charge les certificats RSA pour le chiffrement de jetons. Vérifiez que votre certificat utilise une paire de clés RSA (et non EC/ECDSA).
• Taille de clé trop petite : utilisez une taille de clé d’au moins 2048 bits. Les clés RSA inférieures à 2048 bits peuvent être rejetées.
• Algorithme non pris en charge — Microsoft Entra utilise RSA-OAEP pour l’enveloppement de clé. Vérifiez que votre infrastructure de certificat et d’application prend en charge cet algorithme.

Jetons chiffrés non émis

Symptôme: Votre application reçoit des jetons non chiffrés même si vous avez configuré le déchiffrement de jeton.

Causes et solutions :

• tokenEncryptionKeyId non configuré : vous devez définir explicitement cette propriété via Microsoft Graph. Le chargement du certificat seul n’est pas suffisant.
• Certificat expiré dans l’inscription de l’application : vérifiez que le certificat chargé dans l’inscription de votre application n’a pas expiré. Chargez un nouveau certificat si nécessaire.
• Les jetons d’accès ne sont pas chiffrés : le chiffrement de jeton s’applique uniquement aux jetons d’ID et aux jetons SAML. Les jetons d'accès de Microsoft Entra ne sont pas chiffrés avec votre certificat.

Comparer le déchiffrement des jetons et les informations d’identification du client

Les informations d’identification de déchiffrement des jetons servent un objectif différent des informations d’identification du client. Votre application peut utiliser le même certificat pour les deux, ou utiliser des certificats distincts.

L’exemple suivant montre une configuration qui utilise le même certificat Key Vault pour l’authentification et le déchiffrement de jeton :

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Suivre les bonnes pratiques

Appliquez ces recommandations lorsque vous implémentez le déchiffrement de jeton.

Utiliser Azure Key Vault : stocker des certificats de déchiffrement dans Key Vault pour la gestion centralisée, le contrôle d’accès et la journalisation d’audit.

Planifier la rotation : utilisez toujours une stratégie de rotation avant de déployer le chiffrement des jetons. Incluez les nouveaux certificats et les anciens certificats pendant la période de rotation des certificats.

Utilisez RSA 2048 bits ou des clés plus volumineuses : assurez-vous que vos certificats utilisent des clés RSA d’au moins 2048 bits pour une sécurité adéquate.

Monitor certificate expiration : configurez des alertes dans Azure Key Vault ou votre système de surveillance pour vous avertir avant l’expiration des certificats.

Testez dans un environnement intermédiaire : vérifiez le chiffrement et le déchiffrement des jetons dans un environnement hors production avant de l’activer en production.

Don ne stockez pas de clés privées dans le contrôle de code source : utilisez des Key Vault, des variables d'environnement ou un gestionnaire de secrets pour le stockage de certificats.

Ne supprimez pas l’ancien certificat trop tôt pendant la rotation . Conservez les deux certificats actifs pendant au moins 24 heures pour autoriser l’expiration des jetons mis en cache.

N’activez pas le chiffrement de jeton sans certificat de déchiffrement configuré . Votre application ne traitera pas les jetons s’il ne peut pas les déchiffrer.

Contenu connexe

• Vue d’ensemble des informations d’identification
• Vue d’ensemble du cache de jetons
• Autorisation dans les API web
• Informations d’identification du certificat