Substitution de clé de signature dans la plateforme d’identités Microsoft

Article
11/20/2024

Cet article explique ce que vous devez savoir sur les clés publiques utilisées par la plateforme d’identités Microsoft pour la signature des jetons de sécurité. Il est important de noter que ces clés sont substituées régulièrement, voire immédiatement en cas d’urgence. Toutes les applications qui utilisent la plateforme d’identités Microsoft doivent être en mesure de gérer par programme le processus de substitution de clé. Vous comprendrez comment fonctionnent les clés et comment évaluer l’impact de la substitution sur votre application. Vous apprendrez également à mettre à jour votre application ou à établir un processus de substitution manuel périodique pour gérer la substitution de clé si nécessaire.

Vue d’ensemble des clés de signature dans la plateforme d’identités Microsoft

La plateforme d’identités Microsoft utilise une technique de chiffrement de clés publiques conforme aux normes du secteur pour établir une relation de confiance avec les applications qui l’utilisent. En pratique, cela fonctionne de la façon suivante : La plateforme d’identités Microsoft utilise une clé de signature se composant d’une paire clé publique-clé privée. Quand un utilisateur se connecte à une application qui utilise la plateforme d’identités Microsoft pour l’authentification, la plateforme crée un jeton de sécurité qui contient des informations sur l’utilisateur. Ce jeton est signé par la Plateforme d’identités Microsoft avec sa clé privée avant d’être renvoyé à l’application. Pour vérifier que le jeton est valide et provient bien de la plateforme d’identités Microsoft, l’application doit valider la signature du jeton à l’aide de la clé publique exposée par la plateforme d’identités Microsoft contenue dans le document de métadonnées de fédération SAML/WS-Fed ou le document de découverte OpenID Connect du locataire.

Pour des raisons de sécurité, les clés de signature de la plateforme d’identités Microsoft sont substituées régulièrement, voire immédiatement en cas d’urgence. Aucun intervalle de temps n’est défini ou garanti entre ces substitutions de clé. Toute application intégrée à la Plateforme d’identités Microsoft doit être prête à gérer un événement de substitution de clé, quelle que soit sa fréquence. Si votre application ne gère pas les actualisations soudaines et tente d’utiliser une clé expirée pour vérifier la signature d’un jeton, votre application rejette incorrectement le jeton. Nous vous recommandons d’utiliser des bibliothèques standard pour garantir que les métadonnées de clés sont correctement actualisées et tenues à jour. Dans les cas où des bibliothèques standard ne sont pas utilisées, veillez à ce que l’implémentation respecte les meilleures pratiques.

Plusieurs clés valides sont disponibles à tout moment dans le document de découverte OpenID Connect et dans le document de métadonnées de fédération. Votre application doit être préparée à utiliser n’importe quelle et toutes les clés spécifiées dans le document, car une clé peut être substituée rapidement, une autre la remplacer, et ainsi de suite. Le nombre de clés présentes peut changer au fil du temps, en fonction de l’architecture interne de la plateforme d’identités Microsoft, à mesure que nous prenons en charge de nouvelles plateformes, de nouveaux clouds ou de nouveaux protocoles d’authentification. Ni l’ordre des clés dans la réponse JSON ni l’ordre dans lequel elles ont été exposées ne doivent être considérés comme significatifs pour votre application. Pour en savoir plus sur la structure des données de clé web JSON, vous pouvez consulter le document RFC7517.

Les applications qui ne prennent en charge qu’une seule clé de signature, ou celles qui nécessitent des mises à jour manuelles des clés de signature, sont intrinsèquement moins sécurisées et moins fiables. Elles nécessitent une mise à jour pour utiliser des bibliothèques standard afin de s’assurer qu’elles utilisent toujours des clés de signature à jour, entre autres meilleures pratiques.

Meilleures pratiques relatives à la mise en cache et à la validation des métadonnées de clés

Découvrez les clés à l’aide du point de terminaison propre au locataire, comme décrit dans OpenID Connect (OIDC) et Métadonnées de fédération.
Même si votre application est déployée sur plusieurs locataires, il est toujours recommandé de découvrir et de mettre en cache les clés indépendamment pour chaque locataire desservi par l’application (à l’aide du point de terminaison propre au locataire). Une clé qui est commune à plusieurs locataires aujourd’hui peut devenir distincte à l’avenir.
Utilisez l’algorithme de mise en cache ci-dessous pour vous assurer que la mise en cache est résiliente et sécurisée.

Algorithme de mise en cache des métadonnées de clés :

Nos bibliothèques standard implémentent une mise en cache résiliente et sécurisée des clés. Nous vous recommandons de les utiliser pour éviter de légers défauts dans l’implémentation. Pour les implémentations personnalisées, voici l’algorithme brut :

Considérations d’ordre général :

Le service de validation des jetons doit avoir un cache capable de stocker de nombreuses clés distinctes (entre 10 et 1 000).
Les clés doivent être mises en cache individuellement, en utilisant l’ID de clé (« kid » dans la spécification des métadonnées de clés OIDC) comme clé de cache.
La durée de vie des clés dans le cache doit être configurée sur 24 heures, avec des actualisations toutes les heures. Cela permet de s’assurer que le système peut répondre rapidement aux clés supprimées, mais qu’il dispose d’une durée de cache suffisante pour ne pas être affecté par des problèmes d’extraction de clés.
Les clés doivent être actualisées :
- Une fois au démarrage du processus ou lorsque le cache est vide
- Périodiquement (recommandation : toutes les heures), sous la forme d’un travail en arrière-plan
- Dynamiquement si un jeton reçu a été signé avec une clé inconnue (kid ou tid inconnu dans l’en-tête)

Procédure KeyRefresh (algorithme conceptuel d’IdentityModel)

Initialisation

Le gestionnaire de configuration est configuré avec une adresse spécifique pour extraire les données de configuration et avec les interfaces nécessaires pour récupérer et valider ces données.
Vérification de la configuration

Avant d’extraire de nouvelles données, le système vérifie d’abord si les données existantes sont toujours valides en fonction d’un intervalle d’actualisation prédéfini.
Extraction de données Si les données sont obsolètes ou manquantes, le système se verrouille pour s’assurer qu’un seul thread extrait les nouvelles données afin d’éviter la duplication (et l’insuffisance des threads). Le système tente ensuite de récupérer les dernières données de configuration à partir d’un point de terminaison spécifié.
Validation

Une fois les nouvelles données récupérées, elles sont validées pour vérifier qu’elles répondent aux normes requises et qu’elles ne sont pas endommagées. Les métadonnées ne sont acceptées que lorsqu’une requête entrante a été validée avec les nouvelles clés.
Gestion des erreurs

Si des erreurs se produisent pendant l’extraction de données, elles sont journalisées. Le système continue à fonctionner avec la dernière configuration correcte connue si de nouvelles données ne peuvent pas être extraites.
Mises à jour automatiques Le système vérifie périodiquement et met à jour automatiquement les données de configuration selon l’intervalle d’actualisation (recommandation : 12 heures avec une gigue de plus ou moins 1 heure). Il peut aussi demander manuellement une mise à jour si nécessaire, garantissant ainsi que les données sont toujours à jour.
Validation d’un jeton avec une nouvelle clé Si un jeton arrive avec une clé de signature qui n’est pas encore connue de la configuration, le système tente d’extraire la configuration avec un appel de synchronisation sur le chemin chaud pour gérer les nouvelles clés dans les métadonnées en dehors des mises à jour régulières attendues (au plus toutes les 5 minutes).

Cette approche garantit que le système utilise toujours les données de configuration les plus récentes et valides, tout en gérant correctement les erreurs et en évitant les opérations redondantes.

L’implémentation .NET de cet algorithme est fournie par BaseConfigurationManager. Elle est susceptible de changer en fonction des évaluations de résilience et de sécurité. Vous trouverez également une explication ici.

Procédure KeyRefresh (pseudo-code) :

Cette procédure utilise un timestamp lastSuccessfulRefreshTime global pour empêcher les conditions qui actualisent trop souvent les clés.

OpenID Connect (OIDC)

KeyRefresh(issuer)
{
  // Store cache entries and last successful refresh timestamp per distinct 'issuer'
 
  if (LastSuccessfulRefreshTime is set and more recent than 5 minutes ago) 
    return // without refreshing
 
  // Load keys URI using the tenant-specific OIDC configuration endpoint ('issuer' is the input parameter)
  oidcConfiguration = download JSON from "{issuer}/.well-known/openid-configuration"
 
  // Load list of keys from keys URI
  keyList = download JSON from jwks_uri property of oidcConfiguration
 
  foreach (key in keyList) 
  {
    cache entry = lookup in cache by kid property of key
    if (cache entry found) 
      set expiration of cache entry to now + 24h 
    else 
      add key to cache with expiration set to now + 24h
  }
 
  set LastSuccessfulRefreshTime to now // current timestamp
}

Procédure de démarrage du service :

KeyRefresh pour mettre à jour les clés
Lancer un travail en arrière-plan qui appelle KeyRefresh toutes les heures

Procédure TokenValidation pour valider la clé (pseudo-code) :

ValidateToken(token)
{
  kid = token.header.kid // get key id from token header
  issuer = token.body.iss // get issuer from 'iss' claim in token body
 
  key = lookup in cache by issuer and kid
  if (key found)
  {
     validate token with key and return
  }
  else // key is not found in the cache
  {
    call KeyRefresh(issuer) // to opportunistically refresh the keys for the issuer
    key = lookup in cache by issuer and kid
    if (key found)
    {
      validate token with key and return
    }
    else // key is not found in the cache even after refresh
    {
      return token validation error
    }
  }
}

Comment évaluer si votre application sera affectée et que faire si cela se produit

La manière dont votre application gère la substitution de la clé dépend de variables comme le type d’application ou le protocole d’identité et la bibliothèque utilisés. Les sections ci-dessous évaluent si les types d’application les plus courants sont affectés par la substitution de clé et fournissent des conseils sur la mise à jour de l’application pour prendre en charge la substitution automatique ou mettre la clé à jour manuellement.

Applications clientes natives ayant accès aux ressources
Applications web/API ayant accès aux ressources
Applications web/API protégeant les ressources et créées à l’aide d’Azure App Services
Applications web / API protégeant les ressources en utilisant l’intergiciel ASP.NET OWIN OpenID Connect, WS-Fed ou WindowsAzureActiveDirectoryBearerAuthentication
Applications web/API protégeant les ressources à l'aide de l'intergiciel ASP.NET Core OpenID Connect ou JwtBearerAuthentication
Applications Web/API protégeant les ressources à l'aide du module Node.js passport-azure-ad
Applications web/API protégeant les ressources et créées avec Visual Studio 2015 ou une version ultérieure
Applications web protégeant les ressources et créées avec Visual Studio 2013
API web protégeant les ressources et créées avec Visual Studio 2013
Applications web protégeant les ressources et créées avec Visual Studio 2012
Applications web/API protégeant les ressources avec d’autres bibliothèques ou implémentant manuellement l’un des protocoles pris en charge

Ce guide n’est pas applicable aux :

Une aide distincte sur les clés de signature est disponible pour les applications ajoutées depuis la galerie d’applications Microsoft Entra (y compris les applications personnalisées). Informations complémentaires.
Applications locales publiées via le proxy d’application, qui ne sont pas concernées par les clés de signature.

Applications clientes natives ayant accès aux ressources

Les applications qui ont uniquement accès aux ressources (par exemple, Microsoft Graph, KeyVault, l’API Outlook et d’autres API Microsoft) obtiennent uniquement un jeton et le transmettent au propriétaire de la ressource. Étant donné qu’elles ne protègent pas les ressources, elles n’inspectent pas le jeton et n’ont donc pas besoin de s’assurer qu’il est correctement signé.

Les applications clientes natives, de bureau ou mobiles, appartiennent à cette catégorie et ne sont donc pas affectées par la substitution.

Applications web/API ayant accès aux ressources

Les applications et API web qui utilisent le flux d’application uniquement (informations d’identification du client/certificat client) pour demander des jetons, appartiennent à cette catégorie et ne sont donc pas affectées par la substitution.

Applications web/API protégeant les ressources et créées à l’aide d’Azure App Services

La fonctionnalité d’authentification/d’autorisation d’Azure App Services (EasyAuth) possède déjà la logique nécessaire pour gérer automatiquement la substitution de clé.

Applications web/API protégeant les ressources en utilisant l’intergiciel ASP.NET OWIN OpenID Connect, WS-Fed ou WindowsAzureActiveDirectoryBearerAuthentication

Si votre application utilise l'intergiciel ASP.NET OWIN OpenID Connect, WS-Fed ou WindowsAzureActiveDirectoryBearerAuthentication, elle dispose déjà de la logique nécessaire pour gérer automatiquement le renouvellement des clés.

Vous pouvez vérifier que votre application utilise l’un de ces middlewares en recherchant les extraits de code suivants dans les fichiers Startup.cs ou Startup.Auth.cs de l’application.

app.UseOpenIdConnectAuthentication(
    new OpenIdConnectAuthenticationOptions
    {
        // ...
    });

app.UseWsFederationAuthentication(
    new WsFederationAuthenticationOptions
    {
        // ...
    });

app.UseWindowsAzureActiveDirectoryBearerAuthentication(
    new WindowsAzureActiveDirectoryBearerAuthenticationOptions
    {
        // ...
    });

Applications web/API protégeant les ressources à l’aide du middleware .NET Core OpenID Connect ou JwtBearerAuthentication

Si votre application utilise l'intergiciel ASP.NET OWIN OpenID Connect ou JwtBearerAuthentication, elle dispose déjà de la logique nécessaire pour gérer automatiquement le renouvellement des clés.

Vous pouvez vérifier que votre application utilise l’un de ces middlewares en recherchant les extraits de code suivants dans le fichier Startup.cs ou Startup.Auth.cs de l’application.

app.UseOpenIdConnectAuthentication(
     new OpenIdConnectAuthenticationOptions
     {
         // ...
     });

app.UseJwtBearerAuthentication(
    new JwtBearerAuthenticationOptions
    {
     // ...
     });

Applications Web/API protégeant les ressources à l’aide du module `passport-azure-ad` Node.js

Si votre application utilise le module passport-ad Node.js, elle possède déjà la logique nécessaire pour gérer automatiquement la substitution de clé.

Vous pouvez vérifier que votre application utilise passport-ad en recherchant l’extrait de code suivant dans le fichier app.js de l’application.

var OIDCStrategy = require('passport-azure-ad').OIDCStrategy;

passport.use(new OIDCStrategy({
    //...
));

Applications web/API protégeant les ressources et créées avec Visual Studio 2015 ou une version ultérieure

Si votre application a été générée à l’aide d’un modèle d’application web dans Visual Studio 2015 ou une version ultérieure, et si vous avez sélectionné Comptes professionnels ou scolaires dans le menu Modifier l’authentification, elle possède déjà la logique nécessaire pour gérer automatiquement la substitution de clé. Cette logique, incorporée dans l’intergiciel OWIN OpenID Connect, récupère et met en cache les clés du document de découverte OpenID Connect, et les actualise régulièrement.

Si vous avez ajouté manuellement l’authentification à votre solution, votre application ne possède peut-être pas la logique de substitution de clé nécessaire. Vous pouvez l’écrire vous-même ou suivre les étapes décrites dans Applications web / API protégeant les ressources en utilisant d’autres bibliothèques ou implémentant manuellement un des protocoles pris en charge.

Applications web protégeant les ressources et créées avec Visual Studio 2013

Si votre application a été générée à l’aide d’un modèle d’application web dans Visual Studio 2013 et que vous avez sélectionné Comptes professionnels dans le menu Modifier l’authentification, elle possède déjà la logique nécessaire pour gérer automatiquement la substitution de clé. Cette logique stocke l’identifiant unique de votre organisation et les informations de clé de signature dans deux tables de base de données associées au projet. Vous trouverez la chaîne de connexion de la base de données dans le fichier Web.config du projet.

Si vous avez ajouté manuellement l’authentification à votre solution, votre application ne possède peut-être pas la logique de substitution de clé nécessaire. Vous devez l’écrire vous-même ou suivre les étapes décrites dans Applications web/API protégeant les ressources avec d’autres bibliothèques ou implémentant manuellement l’un des protocoles pris en charge.

Les étapes suivantes vous aident à vérifier le bon fonctionnement de la logique de votre application.

Dans Visual Studio 2013, ouvrez la solution, puis sélectionnez l’onglet Explorateur de serveurs dans la fenêtre de droite.
Développez Connexions de données, DefaultConnection, puis Tables. Recherchez la table IssuingAuthorityKeys, cliquez dessus avec le bouton droit, puis sélectionnez Afficher les données de la table.
La table IssuingAuthorityKeys comporte au moins une ligne correspondant à la valeur de l’empreinte de la clé. Supprimez toutes les lignes de la table.
Cliquez avec le bouton droit sur la table Locataires, puis sélectionnez Afficher les données de la table.
La table Clients comporte au moins une ligne correspondant à un identifiant unique du client de répertoire. Supprimez toutes les lignes de la table. Si vous ne supprimez pas les lignes dans la table Tenants et dans la table IssuingAuthorityKeys, vous obtenez une erreur au moment de l’exécution.
Générez et exécutez l’application. Une fois connecté à votre compte, vous pouvez arrêter l’application.
Revenez à l’Explorateur de serveurs et examinez les valeurs contenues dans les tables IssuingAuthorityKeys et Clients. Vous remarquerez qu’elles ont été automatiquement remplies avec les informations appropriées extraites du document de métadonnées de fédération.

API web protégeant les ressources et créées avec Visual Studio 2013

Si vous avez créé une application API web dans Visual Studio 2013 à l’aide du modèle API web et que vous avez sélectionné Comptes professionnels dans le menu Modifier l’authentification, votre application contient déjà la logique nécessaire.

Si vous avez configuré l’authentification manuellement, suivez les instructions ci-dessous pour savoir comment configurer votre API web afin de mettre automatiquement à jour ses informations de clé.

L’extrait de code suivant montre comment obtenir les clés les plus récentes auprès du document de métadonnées de fédération, puis comment utiliser le Gestionnaire de jetons JWT pour valider le jeton. Cet extrait de code suppose que vous allez utiliser votre propre mécanisme de mise en cache pour conserver la clé afin de valider les jetons futurs de la plateforme d’identité Microsoft, que ce soit dans une base de données, un fichier de configuration ou ailleurs.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.IdentityModel.Tokens;
using System.Configuration;
using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.IdentityModel.Metadata;
using System.ServiceModel.Security;
using System.Threading;

namespace JWTValidation
{
    public class JWTValidator
    {
        private string MetadataAddress = "[Your Federation Metadata document address goes here]";

        // Validates the JWT Token that's part of the Authorization header in an HTTP request.
        public void ValidateJwtToken(string token)
        {
            JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler()
            {
                // Do not disable for production code
                CertificateValidator = X509CertificateValidator.None
            };

            TokenValidationParameters validationParams = new TokenValidationParameters()
            {
                AllowedAudience = "[Your App ID URI goes here]",
                ValidIssuer = "[The issuer for the token goes here, such as https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/]",
                SigningTokens = GetSigningCertificates(MetadataAddress)

                // Cache the signing tokens by your desired mechanism
            };

            Thread.CurrentPrincipal = tokenHandler.ValidateToken(token, validationParams);
        }

        // Returns a list of certificates from the specified metadata document.
        public List<X509SecurityToken> GetSigningCertificates(string metadataAddress)
        {
            List<X509SecurityToken> tokens = new List<X509SecurityToken>();

            if (metadataAddress == null)
            {
                throw new ArgumentNullException(metadataAddress);
            }

            using (XmlReader metadataReader = XmlReader.Create(metadataAddress))
            {
                MetadataSerializer serializer = new MetadataSerializer()
                {
                    // Do not disable for production code
                    CertificateValidationMode = X509CertificateValidationMode.None
                };

                EntityDescriptor metadata = serializer.ReadMetadata(metadataReader) as EntityDescriptor;

                if (metadata != null)
                {
                    SecurityTokenServiceDescriptor stsd = metadata.RoleDescriptors.OfType<SecurityTokenServiceDescriptor>().First();

                    if (stsd != null)
                    {
                        IEnumerable<X509RawDataKeyIdentifierClause> x509DataClauses = stsd.Keys.Where(key => key.KeyInfo != null && (key.Use == KeyType.Signing || key.Use == KeyType.Unspecified)).
                                                             Select(key => key.KeyInfo.OfType<X509RawDataKeyIdentifierClause>().First());

                        tokens.AddRange(x509DataClauses.Select(token => new X509SecurityToken(new X509Certificate2(token.GetX509RawData()))));
                    }
                    else
                    {
                        throw new InvalidOperationException("There is no RoleDescriptor of type SecurityTokenServiceType in the metadata");
                    }
                }
                else
                {
                    throw new Exception("Invalid Federation Metadata document");
                }
            }
            return tokens;
        }
    }
}

Applications web protégeant les ressources et créées avec Visual Studio 2012

Si votre application a été créée dans Visual Studio 2012, vous avez probablement utilisé l’outil Identité et accès pour configurer votre application. Il est également probable que vous utilisiez le registre de validation de nom d’émetteur (VINR). Le VINR est chargé de conserver les informations relatives aux fournisseurs d’identité approuvés (plateforme d’identités Microsoft) et les clés utilisées pour valider les jetons qu’ils émettent. Le VINR permet également de mettre à jour automatiquement les informations de clé stockées dans un fichier Web.config en téléchargeant le dernier document de métadonnées de fédération associé à votre annuaire, en vérifiant si la configuration est à jour avec le dernier document et en mettant à jour l’application pour utiliser la nouvelle clé si nécessaire.

Si vous avez créé votre application à l’aide des exemples de code ou de la documentation détaillée fournis par Microsoft, la logique de substitution de clé est déjà incluse dans votre projet. Vous remarquerez que le code ci-dessous existe déjà dans votre projet. Si votre application ne contient pas déjà cette logique, suivez les étapes ci-dessous pour l’ajouter et vérifier qu’elle fonctionne correctement.

Dans l’Explorateur de solutions, ajoutez une référence à l’assembly System.IdentityModel correspondant au projet approprié.
Ouvrez le fichier Global.asax.cs et ajoutez le code suivant en utilisant les directives :
```
using System.Configuration;
using System.IdentityModel.Tokens;
```

Ajoutez la méthode suivante au fichier Global.asax.cs :

protected void RefreshValidationSettings()
{
 string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config";
 string metadataAddress =
               ConfigurationManager.AppSettings["ida:FederationMetadataLocation"];
 ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath);
}

Appelez la méthode RefreshValidationSettings() dans la méthode Application_Start() dans Global.asax.cs comme illustré ici :
```
protected void Application_Start()
{
 AreaRegistration.RegisterAllAreas();
 ...
 RefreshValidationSettings();
}
```

Une fois ces étapes effectuées, le fichier Web.config de votre application sera mis à jour avec les dernières informations du document de métadonnées de fédération, y compris les clés les plus récentes. Cette mise à jour sera effectuée chaque fois que votre pool d’applications sera recyclé dans IIS. Par défaut, IIS est configuré pour recycler les applications toutes les 29 heures.

Suivez les étapes ci-dessous pour vérifier que la logique de substitution de clé fonctionne correctement.

Vérifiez que votre application utilise bien le code ci-dessus, puis ouvrez le fichier Web.config et accédez au bloc <issuerNameRegistry>. Examinez plus attentivement les quelques lignes suivantes :

<issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry">
     <authority name="https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/">
       <keys>
         <add thumbprint="AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00" />
       </keys>

Dans le paramètre <add thumbprint="">, modifiez la valeur de l’empreinte en remplaçant l’un des caractères par un caractère différent. Enregistrez le fichier Web.config .
Générez puis exécutez l’application. Si vous pouvez terminer le processus de connexion, votre application mettra correctement à jour la clé en téléchargeant les informations requises à partir du document de métadonnées de fédération de votre répertoire. Si vous rencontrez des problèmes de connexion, vérifiez que les modifications apportées à votre application sont correctes en lisant l’article Ajout de la connexion à votre application web à l’aide de la Plateforme d’identités Microsoft, ou en téléchargeant et en inspectant l’exemple de code suivant : Application cloud multilocataire pour Microsoft Entra ID.

Applications web/API protégeant les ressources avec d’autres bibliothèques ou implémentant manuellement l’un des protocoles pris en charge

Si vous utilisez une autre bibliothèque ou si vous avez implémenté manuellement l’un des protocoles pris en charge, vous devez examiner la bibliothèque ou votre implémentation pour vous assurer que la clé est récupérée à partir du document de découverte OpenID Connect ou du document de métadonnées de fédération. Pour le vérifier, vous pouvez rechercher dans votre code ou dans le code de la bibliothèque les appels vers le document de découverte OpenID ou le document de métadonnées de fédération.

Si la clé est stockée quelque part ou codée en dur dans votre application, vous pouvez récupérer la clé et la mettre à jour manuellement en suivant les instructions indiquées à la fin de ce document. Nous vous recommandons fortement d’améliorer votre application pour prendre en charge la substitution automatique en utilisant l’une des approches présentées dans cet article pour éviter les perturbations et les surcharges à l’avenir si la plateforme d’identités Microsoft augmente sa cadence de substitution ou doit effectuer une substitution hors bande en urgence.

Comment tester votre application pour savoir si elle sera affectée

Vous pouvez vérifier si votre application prend en charge le renouvellement automatique des clés en utilisant les scripts PowerShell suivants.

Pour vérifier et mettre à jour les clés de signature avec PowerShell, vous avez besoin du module PowerShell MSIdentityTools .

Installez le module PowerShell MSIdentityTools :
```
Install-Module -Name MSIdentityTools
```
Connectez-vous à l’aide de la commande Connect-MgGraph avec un compte d’administrateur pour donner le consentement aux étendues requises :
```
 Connect-MgGraph -Scope "Application.ReadWrite.All"
```
Obtenir la liste des empreintes numériques de clé de signature disponibles :
```
Get-MsIdSigningKeyThumbprint
```
Choisissez l’une des empreintes clés et configurez l’ID Microsoft Entra pour utiliser cette clé avec votre application (obtenez l’ID de l’application auprès du centre d’administration Microsoft Entra) :
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
```
Testez l’application web en vous connectant pour obtenir un nouveau jeton. La modification de la mise à jour de clé est instantanée, mais veillez à utiliser une nouvelle session de navigateur (à l’aide, par exemple, du mode « InPrivate » d’Internet Explorer, « Incognito » de Chrome ou « Privé » de Firefox) pour vous assurer de recevoir un nouveau jeton.
Pour chacune des empreintes de clé de signature retournées, exécutez la cmdlet Update-MsIdApplicationSigningKeyThumbprint et testez le processus de connexion de votre application web.
Si l’application web vous connecte correctement, elle prend en charge la substitution automatique. Si ce n’est pas le cas, modifiez votre application pour qu’elle prenne en charge la substitution manuelle. Pour plus d’informations, consultez Établissement d’un processus de substitution manuel.

Exécutez le script suivant pour rétablir le comportement normal :

Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default

Comment effectuer une substitution manuelle si votre application ne prend pas en charge la substitution automatique

Si votre application ne prend pas en charge la substitution automatique, vous devez établir un processus permettant de superviser régulièrement les clés de signature de la plateforme d’identités Microsoft et d’effectuer une substitution manuelle en conséquence.

Pour vérifier et mettre à jour les clés de signature avec PowerShell, vous avez besoin du module PowerShell MSIdentityTools.

Installer le module PowerShell MSIdentityTools :
```
Install-Module -Name MSIdentityTools
```
Obtenez la clé de signature la plus récente (obtenez l’ID de locataire à partir du centre d’administration Microsoft Entra) :
```
Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
```
Comparez cette clé à la clé que votre application a actuellement codée en dur ou est configurée pour utiliser.
Si la clé la plus récente est différente de la clé utilisée par votre application, téléchargez la dernière clé de signature :
```
Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
```
Mettez à jour le code ou la configuration de votre application pour utiliser la nouvelle clé.
Configurez l'ID Microsoft Entra pour utiliser cette dernière clé avec votre application (obtenez l'ID de l'application auprès du centre d'administration Microsoft Entra) :
```
Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
```
Testez l’application web en vous connectant pour obtenir un nouveau jeton. La modification de la mise à jour de clé est instantanée, mais veillez à utiliser une nouvelle session de navigateur pour vous assurer de recevoir un nouveau jeton. Par exemple, utilisez le mode « InPrivate » de Microsoft Edge, « Incognito » de Chrome ou « Privé » de Firefox.
Si vous rencontrez des problèmes, revenez à la clé précédente que vous utilisiez et contactez le support Azure :
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <PreviousKeyThumbprint>
```
Une fois que vous avez mis à jour votre application pour prendre en charge la substitution manuelle, rétablissez le comportement normal :
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
```

Partager via

Substitution de clé de signature dans la plateforme d’identités Microsoft

Vue d’ensemble des clés de signature dans la plateforme d’identités Microsoft

Meilleures pratiques relatives à la mise en cache et à la validation des métadonnées de clés

Algorithme de mise en cache des métadonnées de clés :

Considérations d’ordre général :

Procédure KeyRefresh (algorithme conceptuel d’IdentityModel)

Procédure KeyRefresh (pseudo-code) :

Procédure de démarrage du service :

Procédure TokenValidation pour valider la clé (pseudo-code) :

Comment évaluer si votre application sera affectée et que faire si cela se produit

Applications clientes natives ayant accès aux ressources

Applications web/API ayant accès aux ressources

Applications web/API protégeant les ressources et créées à l’aide d’Azure App Services

Applications web/API protégeant les ressources en utilisant l’intergiciel ASP.NET OWIN OpenID Connect, WS-Fed ou WindowsAzureActiveDirectoryBearerAuthentication

Applications web/API protégeant les ressources à l’aide du middleware .NET Core OpenID Connect ou JwtBearerAuthentication

Applications Web/API protégeant les ressources à l’aide du module `passport-azure-ad` Node.js

Applications web/API protégeant les ressources et créées avec Visual Studio 2015 ou une version ultérieure

Applications web protégeant les ressources et créées avec Visual Studio 2013

API web protégeant les ressources et créées avec Visual Studio 2013

Applications web protégeant les ressources et créées avec Visual Studio 2012

Applications web/API protégeant les ressources avec d’autres bibliothèques ou implémentant manuellement l’un des protocoles pris en charge

Comment tester votre application pour savoir si elle sera affectée

Comment effectuer une substitution manuelle si votre application ne prend pas en charge la substitution automatique

Commentaires

Ressources supplémentaires

Partager via

Substitution de clé de signature dans la plateforme d’identités Microsoft

Vue d’ensemble des clés de signature dans la plateforme d’identités Microsoft

Meilleures pratiques relatives à la mise en cache et à la validation des métadonnées de clés

Algorithme de mise en cache des métadonnées de clés :

Considérations d’ordre général :

Procédure KeyRefresh (algorithme conceptuel d’IdentityModel)

Procédure KeyRefresh (pseudo-code) :

Procédure de démarrage du service :

Procédure TokenValidation pour valider la clé (pseudo-code) :

Comment évaluer si votre application sera affectée et que faire si cela se produit

Applications clientes natives ayant accès aux ressources

Applications web/API ayant accès aux ressources

Applications web/API protégeant les ressources et créées à l’aide d’Azure App Services

Applications web/API protégeant les ressources en utilisant l’intergiciel ASP.NET OWIN OpenID Connect, WS-Fed ou WindowsAzureActiveDirectoryBearerAuthentication

Applications web/API protégeant les ressources à l’aide du middleware .NET Core OpenID Connect ou JwtBearerAuthentication

Applications Web/API protégeant les ressources à l’aide du module passport-azure-ad Node.js

Applications web/API protégeant les ressources et créées avec Visual Studio 2015 ou une version ultérieure

Applications web protégeant les ressources et créées avec Visual Studio 2013

API web protégeant les ressources et créées avec Visual Studio 2013

Applications web protégeant les ressources et créées avec Visual Studio 2012

Applications web/API protégeant les ressources avec d’autres bibliothèques ou implémentant manuellement l’un des protocoles pris en charge

Comment tester votre application pour savoir si elle sera affectée

Comment effectuer une substitution manuelle si votre application ne prend pas en charge la substitution automatique

Commentaires

Ressources supplémentaires

Applications Web/API protégeant les ressources à l’aide du module `passport-azure-ad` Node.js