Jetons d’accès de la plateforme d’identités Microsoft

  • Article

Les jetons d’accès permettent aux clients d’appeler de manière sécurisée des API web protégées. Les API Web utilisent des jetons d’accès pour effectuer l’authentification et l’autorisation.

Selon la spécification OAuth, les jetons d'accès sont des chaînes opaques sans format défini. Certains fournisseurs d’identité (IDP) utilisent des GUID et d’autres utilisent des objets blob chiffrés. Le format du jeton d’accès peut dépendre de la configuration de l’API qui l’accepte.

Les API personnalisées inscrites par les développeurs sur la plateforme d’identités Microsoft peuvent choisir parmi deux formats différents de jetons web JSON (jetons JWT), appelés v1.0 et v2.0. Les API développées par Microsoft comme Microsoft Graph ou les API dans Azure ont d’autres formats de jeton propriétaires. Ces formats protégés qui ne peuvent pas être validés peuvent s’agir de jetons chiffrés, de JWT ou de jetons spéciaux de type JWT.

Le contenu du jeton est destiné uniquement à l’API, ce qui signifie que les jetons d’accès doivent être traités comme des chaînes opaques. À des fins de validation et le débogage uniquement, les développeurs peuvent décoder les jetons JWT via un site comme jwt.ms. Les jetons reçus par une API de Microsoft ne sont pas toujours des JWT qui peuvent être décodés.

Les clients doivent utiliser les données de réponse de jeton retournées avec le jeton d’accès pour les données concernant ce qu’il contient. Quand le client demande un jeton d’accès, la plateforme d’identités Microsoft retourne également des métadonnées sur le jeton d’accès que l’application peut consommer. Ces informations incluent le délai d’expiration du jeton d’accès et les étendues dans lesquelles il est valide. Ces données permettent à l’application d’effectuer une mise en cache intelligente des jetons d’accès sans avoir à les analyser eux-mêmes.

Consultez les sections suivantes pour savoir comment une API peut valider et utiliser les revendications dans un jeton d’accès.

Notes

Toute la documentation de cette page, sauf indication contraire, s’applique uniquement aux jetons émis pour les API inscrites. Elle ne s’applique pas aux jetons émis pour les API appartenant à Microsoft, et ces jetons ne peuvent pas être utilisés pour valider la manière dont la plateforme d’identités Microsoft émet des jetons pour une API inscrite.

Formats de jetons

Deux versions de jetons d’accès sont disponibles dans la plateforme d’identités Microsoft : v1.0 et v2.0. Ces versions déterminent les revendications qui se trouvent dans le jeton et vérifient qu’une API web peut contrôler le contenu du jeton.

Les API web ont l’une des versions suivantes sélectionnées comme valeur par défaut lors de l’inscription :

  • v1.0 pour les applications Microsoft Entra uniquement. L’exemple suivant affiche un jeton v1.0 (les clés sont modifiées et les informations personnelles sont supprimées, ce qui empêche la validation des jetons) :

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

  • v2.0 pour les applications qui prennent en charge les comptes consommateur. L’exemple suivant affiche un jeton v2.0 (les clés sont modifiées et les informations personnelles sont supprimées, ce qui empêche la validation des jetons) :

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Définissez la version pour les applications en fournissant la valeur appropriée au paramètre accessTokenAcceptedVersion dans le manifeste de l’application. Les valeurs null et 1 génèrent des jetons v1.0, et la valeur 2 génère des jetons v2.0.

Propriété des jetons

La requête de jeton d’accès implique deux parties : le client qui demande le jeton et la ressource (l’API Web) qui accepte le jeton. La ressource à laquelle le jeton est destiné (son audience) est définie dans la revendication aud d’un jeton. Les clients utilisent le jeton, mais ne doivent pas le comprendre ni tenter de l’analyser. Les ressources acceptent le jeton.

La plateforme d’identités Microsoft prend en charge l’émission de toute version de jeton à partir de n’importe quel point de terminaison de version. Par exemple, quand accessTokenAcceptedVersion a pour valeur 2, un client qui appelle le point de terminaison v1.0 pour obtenir un jeton pour cette ressource reçoit un jeton d’accès v2.0.

Les ressources détiennent toujours leurs jetons en utilisant la revendication aud et sont les seules applications qui peuvent en modifier les détails.

Durée de vie des jetons

La durée de vie par défaut d’un jeton d’accès est variable. Une fois émise, la plateforme d’identité de Microsoft attribue une valeur aléatoire comprise entre 60 et 90 minutes (75 minutes en moyenne) en tant que durée de vie par défaut d’un jeton d’accès. La variation améliore la résilience des services en répartissant la demande de jeton d’accès sur une période, ce qui empêche des pics horaires de trafic vers Microsoft Entra ID.

Les locataires qui n’utilisent pas l’accès conditionnel ont une durée de vie de jeton d’accès par défaut de deux heures pour des clients comme Microsoft Teams et Microsoft 365.

Ajustez la durée de vie d’un jeton d’accès pour contrôler la fréquence à laquelle l’application cliente arrête la session de l’application, ainsi que la fréquence à laquelle elle demande à l’utilisateur de se réauthentifier (en mode silencieux ou interactif). Pour écraser la variation de durée de vie de jeton d’accès par défaut, utilisez la Durée de vie de jeton configurable (CTL, Configurable token lifetime).

Appliquez la variation de durée de vie de jeton par défaut aux organisations pour lesquelles l’évaluation continue de l’accès (CAE, Continuous Access Evaluation) est activée. Appliquez la variation de durée de vie de jeton par défaut même si les organisations utilisent des stratégies CTL. La durée de vie de jeton longue par défaut est comprise entre 20 et 28 heures. Quand le jeton d’accès expire, le client doit utiliser le jeton d’actualisation pour acquérir en mode silencieux un nouveau jeton d’actualisation et un nouveau jeton d’accès.

Les organisations qui utilisent une fréquence de connexion d’accès conditionnel (SIF) pour appliquer la fréquence à laquelle les connexions se produisent ne peuvent pas modifier la variation de durée de vie de jeton d’accès par défaut. Quand les organisations utilisent SIF, le délai entre les invites d’informations d’identification pour un client est égal à la durée de vie du jeton, situé entre 60 et 90 minutes plus l’intervalle de fréquence de connexion.

Voici un exemple illustrant le fonctionnement de la variation de durée de vie de jeton par défaut avec la fréquence de connexion. Supposons qu’une organisation définit une fréquence de connexion horaire. L’intervalle de connexion réel se produit entre 1 et 2,5 heures lorsque le jeton dispose d’une durée de vie comprise entre 60 et 90 minutes en raison de la variation de durée de vie de jeton.

Si un utilisateur disposant d’un jeton d’une durée de vie d’une heure effectue une connexion interactive à la 59e minute, aucune invite d’informations d’identification ne s’affiche, car la connexion se produit sous le seuil SIF. Si un nouveau jeton dispose d’une durée de vie de 90 minutes, l’utilisateur ne voit pas d’invite d’informations d’identification pendant encore une heure et demie. Lors d’une tentative de renouvellement en mode silencieux, Microsoft Entra ID exige une invite d’informations d’identification, car la durée totale de la session dépasse le paramètre de fréquence de connexion d’une heure. Dans cet exemple, l’écart de temps entre les invites d’informations d’identification dues à l’intervalle SIF et la variation de durée de vie du jeton est de 2,5 heures.

Valider les jetons

Les applications ne doivent pas toutes valider des jetons. Dans des scénarios spécifiques uniquement, les applications doivent valider un jeton :

  • Les API web doivent valider les jetons d’accès qui leur sont envoyés par un client. Ils doivent accepter uniquement des jetons contenant l’un de leurs URI AppId en tant que revendicationaud.
  • Les applications web confidentielles doivent valider les jetons d’ID, qui leur sont envoyés à l’aide du navigateur de l’utilisateur dans le flux hybride, avant d’autoriser l’accès aux données d’un utilisateur ou d’établir une session.

Si aucun des scénarios décrits précédemment ne s’applique, il n’est pas nécessaire de valider le jeton. Les clients publics, tels que des applications natives, de bureau ou monopage, ne bénéficient pas de la validation des jetons d’ID, car l’application communique directement avec le fournisseur d’identité où la protection SSL veille à la validité des jetons d’ID. Ils ne doivent pas valider les jetons d’accès, car c’est à l’API web de les valider, et non au client.

Les API et les applications web doivent uniquement valider les jetons dotés d’une revendication aud qui correspond à l’application. D’autres ressources peuvent avoir des règles de validation de jeton personnalisées. Par exemple, vous ne pouvez pas valider des jetons pour Microsoft Graph en fonction de ces règles en raison de leur format protégé. La validation et l’acceptation de jetons destinés à une autre ressource constituent un exemple du problème d’adjoint confus.

Si l’application doit valider un jeton d’ID ou d’accès, elle doit d’abord valider la signature du jeton et son émetteur par rapport aux valeurs figurant dans le document de découverte OpenID.

L’intergiciel Microsoft Entra comprend des fonctionnalités de validation des jetons d’accès. Consultez ces exemples pour en trouver un dans le langage approprié. Il existe également plusieurs bibliothèques open source tierces disponibles pour la validation de jetons JWT. Pour plus d’informations sur les exemples de code et les bibliothèques d’authentification, consultez Bibliothèques d’authentification. Si votre application web ou API web est sur ASP.NET ou ASP.NET Core, utilisez Microsoft.Identity.Web qui gère la validation à votre place.

Jetons v1.0 et v2.0

  • Lorsque votre application web /API valide un jeton v1.0 ( revendication ver ="1.0"), elle doit lire le document de métadonnées OpenID Connect à partir du point de terminaison v1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), même si l’autorité configurée pour votre API web est une autorité v2.0.
  • Lorsque votre application web/API valide un jeton v2.0 ( revendication ver ="2.0"), elle doit lire le document de métadonnées OpenID Connect à partir du point de terminaison v2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), même si l’autorité configurée pour votre API web est une autorité v1.0.

Les exemples suivants supposent que votre application valide un jeton d’accès v2.0 (et référence donc les versions v2.0 des clés et documents de métadonnées OIDC). Supprimez simplement « /v2.0 » dans l’URL si vous validez des jetons v1.0.

Valider l’émetteur

OpenID Connect Core indique « Identificateur de l’émetteur [...] DOIT correspondre exactement à la valeur de la revendication iss (émetteur) ». Pour les applications qui utilisent un point de terminaison de métadonnées spécifique au locataire (comme https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration ou https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), rien de plus n’est nécessaire.

Microsoft Entra ID dispose d’une version indépendante du locataire du document disponible à l’adresse https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Ce point de terminaison retourne une valeur d’émetteur https://login.microsoftonline.com/{tenantid}/v2.0. Les applications peuvent utiliser ce point de terminaison indépendant du locataire pour valider les jetons de chaque locataire avec les modifications suivantes :

  1. Au lieu de s’attendre à ce que la revendication de l’émetteur dans le jeton corresponde exactement à la valeur de l’émetteur à partir des métadonnées, l’application doit remplacer la valeur {tenantid} dans les métadonnées de l’émetteur par le tenantid qui se trouve dans la cible de la requête actuelle, puis vérifier la correspondance exacte.

  2. L’application doit utiliser la propriété issuer retournée à partir du point de terminaison de clés pour restreindre l’étendue des clés.

    • Les clés qui ont une valeur d’émetteur telle que https://login.microsoftonline.com/{tenantid}/v2.0 peuvent être utilisées avec n’importe quel émetteur de jeton correspondant.
    • Les clés qui ont une valeur d’émetteur comme https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 doivent être utilisées uniquement avec une correspondance exacte.

    Le point de terminaison de clé indépendant du locataire de Microsoft Entra (https://login.microsoftonline.com/common/discovery/v2.0/keys) retourne un document comme suit :

    {
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

  3. Les applications qui utilisent la revendication tenantid (tid) de Microsoft Entra comme limite d’approbation, au lieu de la revendication d’émetteur standard, doivent s’assurer que la revendication tenant-id est un GUID, mais aussi que l’émetteur et le tenantid correspondent.

L’utilisation de métadonnées indépendantes du locataire est plus efficace pour les applications qui acceptent les jetons de nombreux locataires.

Remarque

Avec les métadonnées indépendantes du locataire Microsoft Entra, les revendications doivent être interprétées dans le locataire, tout comme sous OpenID Connect standard, les revendications sont interprétées dans l’émetteur. Autrement dit, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} et {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} décrivent différents utilisateurs, même si le sub est identique, car les revendications telles que sub sont interprétées dans le contexte de l’émetteur/locataire.

valider la signature

Un JWT contient trois segments séparés par le caractère .. Le premier segment est appelé l’en-tête, le deuxième le corps et le troisième la signature. Utilisez le segment de signature pour évaluer l’authenticité du jeton.

Microsoft Entra ID émet des jetons signés à l’aide d’algorithmes de chiffrement asymétrique standard, tel que RS256. L’en-tête du JWT contient des informations sur la clé et la méthode de chiffrement utilisées pour signer le jeton :

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

La revendication alg indique l’algorithme utilisé pour signer le jeton, tandis que la revendication kid indique la clé publique spécifique utilisée pour le valider.

À tout moment, Microsoft Entra ID peut signer un jeton d’identification à l’aide de l’un des ensembles de paires de clés publique-privée. Microsoft Entra ID alterne le jeu de clés possible de façon périodique. C’est pour cela que vous devez écrire l’application de manière à gérer automatiquement ces changements de clés. Pour vérifier les mises à jour apportées aux clés publiques utilisées par Microsoft Entra ID, spécifiez une fréquence raisonnable d’environ 24 heures.

Acquérez les données de la clé de signature nécessaires pour valider la signature en utilisant le document de métadonnées OpenID Connect à l’emplacement suivant :

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Conseil

Essayez cela dans un navigateur : URL

Les informations suivantes décrivent le document de métadonnées :

  • Objet JSON qui contient diverses informations utiles, comme l’emplacement des différents points de terminaison nécessaires pour effectuer l’authentification OpenID Connect.
  • Inclut un jwks_uri, qui indique l’emplacement de l’ensemble de clés publiques correspondant aux clés privées utilisées pour signer les jetons. La clé web JSON (JWK) située sous jwks_uri contient toutes les informations sur les clés publiques utilisées à cet instant donné. RFC 7517 décrit le format JWK. L’application peut utiliser la revendication kid dans l’en-tête JWT pour sélectionner la clé publique, décrite dans ce document, qui correspond à la clé privée utilisée pour signer un jeton particulier. Elle peut ensuite procéder à la validation des signatures à l’aide de la clé publique correcte et de l’algorithme indiqué.

Notes

Utilisez la revendication kid pour valider le jeton. Alors que les jetons v1.0 contiennent à la fois les revendications x5t et kid, les jetons v2.0 contiennent uniquement la revendication kid.

La procédure de validation des signatures sort du cadre de ce document. De nombreuses bibliothèques open source sont disponibles pour faciliter la validation de signature si nécessaire. Toutefois, la plateforme d’identités Microsoft dispose d’une extension de signature de jeton pour les normes : des clés de signature personnalisées.

Si l’application a des clés de signature personnalisées en raison de l’utilisation de la fonctionnalité claims-mapping, ajoutez un paramètre de requête appid qui contient l’ID de l’application. Pour la validation, utilisez jwks_uri qui indique les informations de clé de signature de l’application. Par exemple : https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 contient un jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Valider l’émetteur

Les applications web validant des jetons d’ID et les API web validant des jetons d’accès doivent valider l’émetteur du jeton (revendication iss) par rapport à :

  1. l’émetteur disponible dans le document de métadonnées OpenID Connect associé à la configuration de l’application (autorité). Le document de métadonnées à vérifier dépend des éléments suivants :
    • la version du jeton
    • les comptes pris en charge par votre application.
  2. l’ID de tenant (locataire (revendication tid) du jeton,
  3. l’émetteur de la clé de signature.

Applications à tenant unique

OpenID Connect Core indique « Identificateur de l’émetteur [...] DOIT correspondre exactement à la valeur de la revendication iss (émetteur) ». Pour les applications qui utilisent un point de terminaison de métadonnées spécifique au locataire, tel que https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration ou https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Les applications à locataire unique sont des applications qui prennent en charge :

  • Comptes dans un annuaire organisationnel (exemple-tenant-id uniquement) : https://login.microsoftonline.com/{example-tenant-id}
  • Comptes Microsoft personnels uniquement : https://login.microsoftonline.com/consumers (consommateurs étant un surnom pour le tenant 9188040d-6c67-4c5b-b112-36a304b66dad)

Applications multilocataires

Microsoft Entra ID prend également en charge les applications multi-locataires. Ces applications prennent en charge les éléments suivants :

  • Comptes dans n’importe quel répertoire organisationnel (n’importe quel répertoire Microsoft Entra) : https://login.microsoftonline.com/organizations
  • Les comptes dans un annuaire organisationnel (tout annuaire Microsoft Entra) et comptes Microsoft personnels (par exemple Skype, Xbox) : https://login.microsoftonline.com/common

Pour ces applications, Microsoft Entra ID expose des versions indépendantes du locataire du document OIDC à l’adresse https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration et https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration respectivement. Ces points de terminaison retournent une valeur d’émetteur qui est un modèle paramétré par tenantid: https://login.microsoftonline.com/{tenantid}/v2.0. Les applications peuvent utiliser ces points de terminaison indépendant du locataire pour valider les jetons de chaque locataire avec les stipulations suivantes :

  • Valider l’émetteur de clé de signature
  • Au lieu de s’attendre à ce que la revendication de l’émetteur dans le jeton corresponde exactement à la valeur de l’émetteur à partir des métadonnées, l’application doit remplacer la {tenantid}valeur dans les métadonnées de l’émetteur par l’ID du locataire qui est la cible de la requête actuelle, puis vérifier la correspondance exacte (tidrevendication du jeton).
  • Validez que la revendication tid est un GUID et que la revendication iss est de la forme https://login.microsoftonline.com/{tid}/v2.0, où {tid} est la revendication tid exacte. Cette validation lie le locataire à l’émetteur et à l’étendue de la clé de signature créant une chaîne d’approbation.
  • Utilisez la revendication tid lorsque vous localisez des données associées à l’objet de la revendication. En d’autres termes, la revendication tid doit faire partie de la clé utilisée pour accéder aux données de l’utilisateur.

Valider l’émetteur de clé de signature

Les applications utilisant les métadonnées indépendantes du locataire v2.0 doivent valider l’émetteur de clé de signature.

Document des clés et émetteur de clé de signature

Comme indiqué, votre application accède aux clés utilisées pour signer les jetons à partir du document OpenID Connect. Elle obtient le document des clés correspondant en accédant à l’URL exposée dans la propriété jwks_uri du document OpenIdConnect.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

La valeur {example-tenant-id} peut être remplacée par un GUID, un nom de domaine ou commun, des organisations et des consommateurs

Les documents keys exposés par Azure AD v2.0 contiennent, pour chaque clé, l’émetteur qui utilise cette clé de signature. Par exemple, le point de terminaison https://login.microsoftonline.com/common/discovery/v2.0/keys de clé « commun » indépendant du locataire retourne un document semblable à :

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Validation de l’émetteur de clé de signature

L’application doit utiliser la propriété issuer du document des clés associée à la clé utilisée pour signer le jeton afin de limiter l’étendue des clés :

  • Les clés qui ont une valeur d’émetteur avec un GUID tel que https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 ne doivent être utilisées que lorsque la revendication iss dans le jeton correspond exactement à la valeur.
  • Les clés qui ont une valeur d’émetteur modèle comme https://login.microsoftonline.com/{tenantid}/v2.0 ne doivent être utilisées que lorsque la revendication iss dans le jeton correspond à cette valeur après avoir remplacé la revendication tid dans le jeton par l’espace réservé {tenantid}.

L’utilisation de métadonnées indépendantes du tenant est plus efficace pour les applications qui acceptent des jetons de nombreux tenants.

Remarque

Avec les métadonnées indépendantes du locataire Microsoft Entra, les revendications doivent être interprétées dans le locataire, tout comme sous OpenID Connect standard, les revendications sont interprétées dans l’émetteur. Autrement dit, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} et {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} décrivent différents utilisateurs, même si le sub est identique, car les revendications telles que sub sont interprétées dans le contexte de l’émetteur/locataire.

Récapitulatif

Voici un pseudo-code qui récapitule comment valider l’émetteur et l’émetteur de clé de signature :

  1. Extraire des clés à partir d’une URL de métadonnées configurée
  2. Vérifier que le jeton il est signé avec l’une des clés publiées, échouer si ce n’est pas le cas
  3. Identifiez la clé dans les métadonnées en fonction de l’en-tête enfant. Vérifiez la propriété « émetteur » jointe à la clé dans le document de métadonnées : 
    var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Voir aussi

Étapes suivantes