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

Les jetons d’accès permettent aux clients d’appeler de manière sécurisée des API web protégées. Les jetons d’accès sont utilisés par les API web 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 façon dont l’API qui accepte le jeton est configurée.

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 propriétaires peuvent être des jetons chiffrés, des jetons JWT ou des jetons de type JWT spéciaux qui ne sont pas validés.

Les clients doivent traiter les jetons d’accès comme des chaînes opaques, car leur contenu n’est destiné qu’à l’API. À 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 pour une API Microsoft peuvent ne pas toujours être un jeton JWT et ne peuvent pas toujours être décodés.

Pour plus d’informations sur le contenu du jeton d’accès, les clients doivent utiliser les données de réponse de jeton retournées avec le jeton d’accès au client. 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 Azure AD uniquement. L’exemple suivant montre un jeton v1.0 (cet exemple de jeton n’est pas validé, car les clés ont permuté avant la publication et des informations personnelles ont été supprimées) :

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
    
  • v2.0 pour les applications qui prennent en charge les comptes consommateur. L’exemple suivant montre un jeton v1.0 (cet exemple de jeton n’est pas validé, car les clés ont permuté avant la publication et des informations personnelles ont été supprimées) :

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
    

La version peut être définie 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

Deux parties sont impliquées dans une demande de jeton d’accès : le client qui demande le jeton et la ressource (l’API web) qui accepte le jeton. La revendication aud dans un jeton indique la ressource à laquelle le jeton est destiné (son audience). 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 : ils ne sont pas liés. 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.

Revendications dans les jetons d’accès

Les TJW sont divisés en trois parties :

  • En-tête : fournit des informations sur la façon de valider le jeton, notamment des informations sur le type du jeton et la façon dont il a été signé.
  • Charge utile : contient toutes les données importantes concernant l’utilisateur ou l’application qui tente d’appeler le service.
  • Signature : ressource de base utilisée pour valider le jeton.

Chaque partie est séparée par un point (.) et encodée séparément en base64.

Les revendications ne sont présentes que lorsqu’elles sont renseignées par une valeur. Une application ne doit pas dépendre de la présence d’une revendication. Exemples : pwd_exp (tous les locataires n’ont pas besoin que leur mot de passe expire) ou family_name (les flux d’ informations d’identification client se font au nom d’applications qui ne portent pas de noms). Les revendications utilisées pour la validation des jetons d’accès sont toujours présentes.

Certaines revendications sont utilisées pour aider la plateforme d’identités Microsoft à sécuriser les jetons à réutiliser. Ces revendications portent la mention Opaque dans la description pour indiquer qu’elles ne sont pas destinées à une utilisation publique. Ces revendications peuvent apparaître ou non dans un jeton, et de nouvelles revendications peuvent être ajoutées sans préavis.

Revendications de l’en-tête

Revendication Format Description
typ Chaîne : toujours JWT Indique que le jeton est un JWT.
alg String Indique l’algorithme utilisé pour signer le jeton, par exemple, RS256.
kid String Spécifie l’empreinte numérique de la clé publique qui peut être utilisée pour valider cette signature du jeton. Émis dans les jetons d’accès v1.0 et v2.0.
x5t String Fonctions identiques (en utilisation et en valeur) à kid. x5t est une revendication héritée émise uniquement dans les jetons d’accès v1.0 à des fins de compatibilité.

Revendications de la charge utile

Revendication Format Description
aud Chaîne, URI d’ID d’application ou GUID Identifie l’audience ciblée du jeton. L’API doit valider cette valeur et rejeter le jeton si la valeur ne correspond pas. Dans les jetons v2.0, cette valeur est toujours l’ID client de l’API. Dans les jetons v1.0, il peut s’agir de l’ID client ou de l’URI de ressource utilisé dans la demande. La valeur peut dépendre de la façon dont le client a demandé le jeton.
iss Chaîne, URI de service de jeton de sécurité (STS) Identifie le service de jeton de sécurité (STS) qui construit et retourne le jeton, ainsi que le locataire Azure AD dans lequel l’utilisateur a été authentifié. Si le jeton émis est un jeton v2.0 (consultez la revendication ver), l’URI se termine par /v2.0. La partie GUID qui indique que l’utilisateur est un utilisateur consommateur d’un compte Microsoft est 9188040d-6c67-4c5b-b112-36a304b66dad. L’application peut utiliser la partie GUID de la revendication pour restreindre l’ensemble des locataires qui peuvent se connecter à l’application, le cas échéant.
idp Chaîne, généralement un URI STS Enregistre le fournisseur d’identité qui a authentifié le sujet du jeton. Cette valeur est identique à la valeur de la revendication de l’émetteur sauf si le compte d’utilisateur n’est pas dans le même locataire que l’émetteur, comme les invités. Si la revendication n’est pas présente, la valeur iss peut être utilisée à la place. Pour les comptes personnels utilisés dans un contexte organisationnel (par exemple, un compte personnel invité dans un locataire Azure AD), la revendication idp peut être « live.com » ou un URI STS contenant le locataire de compte Microsoft 9188040d-6c67-4c5b-b112-36a304b66dad.
iat int, horodatage UNIX Indique quand l’authentification de ce jeton a eu lieu.
nbf int, horodatage UNIX Indique le délai avant lequel le jeton JWT ne doit pas être accepté pour être traité.
exp int, horodatage UNIX Indique le délai d’expiration à partir duquel le jeton JWT ne doit pas être accepté pour être traité. Une ressource peut également rejeter le jeton avant cette heure. Le rejet peut avoir lieu quand une modification de l’authentification est nécessaire ou quand une révocation de jeton a été détectée.
aio Chaîne opaque Revendication interne utilisée par Azure AD pour enregistrer des données afin de réutiliser les jetons. Les ressources ne doivent pas utiliser cette revendication.
acr Chaîne, un 0 ou un 1, présente uniquement dans les jetons v1.0 La valeur 0 de la revendication « Classe de contexte d’authentification » indique que l’authentification de l’utilisateur final n’a pas répondu aux exigences de la norme ISO/CEI 29115.
amr Tableau JSON de chaînes, présent uniquement dans les jetons v1.0 Identifie comment le sujet du jeton a été authentifié.
appid Chaîne, un GUID, présente uniquement dans les jetons v1.0 ID de l’application du client utilisant le jeton. L'application peut agir pour elle-même ou pour le compte d'un utilisateur. L'ID d'application représente généralement un objet d’application, mais elle peut également représenter un objet du principal du service dans Azure AD.
azp Chaîne, un GUID, présente uniquement dans les jetons v2.0 Remplacement pour appid. ID de l’application du client utilisant le jeton. L'application peut agir pour elle-même ou pour le compte d'un utilisateur. L'ID d'application représente généralement un objet d’application, mais elle peut également représenter un objet du principal du service dans Azure AD.
appidacr Chaîne, un 0, un 1 ou un 2, présente uniquement dans les jetons v1.0 Indique comment le client a été authentifié. Pour un client public, la valeur est 0. Si l’ID client et la clé secrète client sont utilisés, la valeur est 1. Si un certificat client a été utilisé pour l’authentification, la valeur est 2.
azpacr Chaîne, un 0, un 1 ou un 2, présente uniquement dans les jetons v2.0 Remplacement pour appidacr. Indique comment le client a été authentifié. Pour un client public, la valeur est 0. Si l’ID client et la clé secrète client sont utilisés, la valeur est 1. Si un certificat client a été utilisé pour l’authentification, la valeur est 2.
preferred_username Chaîne, présente uniquement dans les jetons v2.0. Nom d’utilisateur principal qui représente l’utilisateur. La valeur peut être une adresse e-mail, un numéro de téléphone ou un nom d’utilisateur générique sans format spécifié. La valeur est mutable et peut changer au fil du temps. Dans la mesure où la valeur est mutable, elle ne doit pas être utilisée pour prendre des décisions d’autorisation. La valeur peut toutefois être utilisée pour les indications sur le nom d’utilisateur et dans une interface utilisateur explicite en tant que nom d’utilisateur. L’étendue profile est requise afin de recevoir cette revendication.
name String Fournit une valeur contrôlable de visu qui identifie le sujet du jeton. Il n’est pas certain que cette valeur soit unique. Elle est mutable et utilisée uniquement à des fins d’affichage. L’étendue profile est requise afin de recevoir cette revendication.
scp Chaîne, liste d’étendues séparées par des espaces Ensemble des étendues exposées par l’application pour lesquelles l’application client a demandé (et reçu) un consentement. L’application doit vérifier la validité de ces étendues et prendre des décisions d’autorisation en fonction de leur valeur. Uniquement inclus pour les jetons utilisateur.
roles Tableau de chaînes, une liste d’autorisations Ensemble des autorisations exposées par l’application que l’application ou l’utilisateur faisant la demande sont autorisés à appeler. Pour les jetons d’application, cet ensemble d’autorisations est utilisé durant le flux d’informations client (v1.0, v2.0) à la place des étendues utilisateur. Pour les jetons utilisateur, cet ensemble de valeurs est renseigné avec les rôles auxquels l’utilisateur a été affecté sur l’application cible.
wids Tableau de GUID RoleTemplateID Indique les rôles au niveau du locataire attribués à cet utilisateur, à partir de la section des rôles présents dans les rôles intégrés Azure AD. Cette revendication est définie pour chaque application, via la propriété groupMembershipClaims du manifeste d’application. Il est requis de la définir sur All ou DirectoryRole. Peut ne pas être présent dans les jetons obtenus via le flux implicite en raison des problèmes de longueur de jeton.
groups Tableau de GUID JSON Fournit les ID d’objet qui représentent les appartenances aux groupes du sujet. Ces valeurs sont uniques et peuvent être utilisées en toute sécurité pour la gestion des accès, par exemple, l’autorisation d’accès à une ressource. Les groupes inclus dans la revendication des groupes sont configurés pour chaque application, via la propriété groupMembershipClaims du manifeste d’application. Une valeur null exclut tous les groupes, une valeur SecurityGroup inclut uniquement les appartenances aux groupes de sécurité Active Directory, et une valeur All inclut les groupes de sécurité et les listes de distribution Microsoft 365.

Consultez la revendication hasgroups pour plus d’informations sur l’utilisation de la revendication groups avec l’octroi implicite. Pour les autres flux, si le nombre de groupes auxquels l’utilisateur appartient dépasse 150 pour SAML et 200 pour JWT, alors Azure AD ajoute une revendication de dépassement aux sources de revendication. Les sources de revendication pointent sur le point de terminaison Microsoft Graph contenant la liste des groupes pour l’utilisateur.
hasgroups Boolean Le cas échéant, toujours true, indique que l’utilisateur appartient à au moins un groupe. Utilisé à la place de la revendication groups pour JWT dans les flux d’octroi implicites si la revendication des groupes complets étend le fragment URI au-delà des limites de longueur d’URL (actuellement, six groupes ou plus). Indique que le client doit utiliser l’API Microsoft Graph pour déterminer les groupes de l’utilisateur (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1 Objet JSON Pour les demandes de jetons dont la longueur n’est pas limitée (voir hasgroups) mais qui sont toujours trop volumineuses pour le jeton, un lien vers la liste complète des groupes pour l’utilisateur est inclus. Pour les jetons JWT en tant que revendication distribuée, pour SAML en tant que nouvelle revendication à la place de la revendication groups.

Exemple de valeur JWT :
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub Chaîne Principal sur lequel portent les assertions d’informations du jeton, comme l’utilisateur d’une application. Cette valeur est immuable et ne peut pas être réattribuée ou réutilisée. Vous pouvez l’utiliser pour effectuer des vérifications d’autorisation en toute sécurité, comme lorsque le jeton est utilisé pour accéder à une ressource et qu’il peut servir de clé dans les tables de base de données. Étant donné que le sujet est toujours présent dans les jetons émis par Azure AD, utilisez cette valeur dans un système d’autorisation à usage général. Toutefois, le sujet est un identificateur par paire, qui est unique à un ID d’application donné. Si un utilisateur se connecte à deux applications différentes à l’aide de deux ID client différents, ces applications reçoivent deux valeurs différentes pour la revendication du sujet. Deux valeurs différentes peuvent être souhaitées ou non en fonction de vos exigences en matière d’architecture et de confidentialité. Consultez également la revendication oid (qui reste la même sur les applications d’un même locataire).
oid Chaîne, GUID Identificateur immuable pour le demandeur, qui correspond à l’utilisateur ou au principal de service dont l’identité a été vérifiée. Il peut également être utilisé pour effectuer des vérifications d’autorisation en toute sécurité et en tant que clé dans les tables de base de données. Cet ID identifie de manière unique le demandeur entre les applications. Deux applications différentes se connectant au même utilisateur reçoivent la même valeur dans la revendication oid. oid peut être utilisé lors de la formulation de requêtes auprès de services Microsoft en ligne, tels que Microsoft Graph. Microsoft Graph renvoie cet ID en tant que propriété id pour un compte d’utilisateur donné. oid permettant à plusieurs applications de corréler des principaux, l’étendue profile est requise afin de recevoir cette revendication pour des utilisateurs. Si un utilisateur existe dans plusieurs locataires, l’utilisateur contient un ID d’objet différent dans chaque locataire. Les comptes sont considérés comme différents, même si l’utilisateur se connecte à chaque compte avec les mêmes informations d’identification.
tid Chaîne, GUID Représente le locataire auquel l’utilisateur se connecte. Pour les comptes professionnels et scolaires, le GUID correspond à l’ID de locataire immuable de l’organisation à laquelle l’utilisateur se connecte. Pour les connexions au locataire de compte Microsoft personnel (services tels que Xbox, Teams à usage personnel ou Outlook), la valeur est 9188040d-6c67-4c5b-b112-36a304b66dad. Pour recevoir cette revendication, l’application doit demander l’étendue profile.
unique_name Chaîne, présente uniquement dans les jetons v1.0 Fournit une valeur contrôlable de visu qui identifie le sujet du jeton. Il n’est pas certain que cette valeur soit unique au sein d’un locataire. Elle doit être utilisée uniquement à des fins d’affichage.
uti String Revendication d’identificateur de jeton, équivalente à jti dans la spécification JWT. Identificateur unique par jeton qui respecte la casse.
rh Chaîne opaque Revendication interne utilisée par Azure pour revalider des jetons. Les ressources ne doivent pas utiliser cette revendication.
ver Chaîne, 1.0 ou 2.0 Indique la version du jeton d’accès.

Revendication de dépassement des groupes

Azure AD limite le nombre d’ID d’objet qu’il inclut dans la revendication de groupes pour rester dans la limite de taille de l’en-tête HTTP. Si un utilisateur est membre d’un nombre de groupes supérieur à la limite de dépassement (150 pour les jetons SAML, 200 pour les jetons JWT et seulement 6 en cas d’émission via le flux implicite), Azure AD n’émet pas la revendication des groupes dans le jeton. Au lieu de cela, il inclut une revendication de dépassement dans le jeton qui indique à l’application d’interroger l’API Microsoft Graph pour récupérer l’appartenance de groupe de l’utilisateur.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Utilisez la valeur BulkCreateGroups.ps1 fournie dans le dossier App Creation Scripts pour aider à tester les scénarios de dépassement.

Revendications de base v1.0

Les revendications suivantes sont incluses dans les jetons v1.0, le cas échéant, mais pas dans les jetons v2.0 par défaut. Pour utiliser ces revendications pour v2.0, l’application les demande à l’aide de revendications facultatives.

Revendication Format Description
ipaddr String Adresse IP à partir de laquelle l’utilisateur s’est authentifié.
onprem_sid Chaîne, au format SID Lorsque l’utilisateur dispose d’une authentification locale, cette revendication fournit son SID. Utilisez cette revendication pour l’autorisation dans des applications héritées.
pwd_exp int, horodatage UNIX Indique la date d’expiration du mot de passe de l’utilisateur.
pwd_url String URL vers laquelle les utilisateurs peuvent être redirigés pour réinitialiser leur mot de passe.
in_corp boolean Indique si le client se connecte à partir du réseau d’entreprise. Dans le cas contraire, la revendication n’est pas incluse.
nickname String Autre nom de l’utilisateur, distinct du nom de famille et du prénom.
family_name String Fournit le nom de famille de l’utilisateur tel que défini sur l’objet utilisateur.
given_name String Fournit le prénom de l’utilisateur tel que défini sur l’objet utilisateur.
upn String Nom d’utilisateur. Il peut s’agir d’un numéro de téléphone, d’une adresse électronique ou d’une chaîne non formatée. Ne doit être utilisé qu’à des fins d’affichage et pour fournir des indications sur le nom d’utilisateur dans les scénarios de réauthentification.

Revendication amr

Les identités peuvent s’authentifier de différentes manières appropriées à l’application. La revendication amr est un tableau pouvant contenir plusieurs éléments, par exemple ["mfa", "rsa", "pwd"], pour les authentifications qui utilisent à la fois un mot de passe et l’application Authenticator.

Valeur Description
pwd Authentification par mot de passe : mot de passe Microsoft d’un utilisateur ou clé secrète client d’une application.
rsa L’authentification reposait sur la preuve d’une clé RSA, par exemple avec l’application Microsoft Authenticator. Cette valeur indique également si l’authentification a été effectuée par un jeton JWT auto-signé avec un certificat X509 appartenant à un service.
otp Code secret à usage unique utilisant un e-mail ou un SMS.
fed Une assertion d’authentification fédérée (par exemple JWT ou SAML) a été utilisée.
wia Authentification Windows intégrée
mfa L’authentification multifacteur a été utilisée. Quand cette revendication est présente, les autres méthodes d’authentification sont incluses.
ngcmfa Équivalente à mfa, utilisée pour le provisionnement de certains types avancés d’informations d’identification.
wiaormfa L’utilisateur a utilisé Windows ou un identifiant MFA pour s’authentifier.
none Aucune authentification n’a été effectuée.

Durée de vie de jeton d’accès

La durée de vie par défaut d’un jeton d’accès est variable. Une fois un jeton d’accès émis, sa durée de vie par défaut se voit attribuer une valeur aléatoire comprise entre 60 et 90 minutes (75 minutes en moyenne). 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 Azure AD.

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 les clients, tels que Microsoft Teams et Microsoft 365.

Vous pouvez ajuster la durée de vie d’un jeton d’accès pour contrôler la fréquence à laquelle l’application cliente met fin à 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 remplacer la variation de durée de vie des jetons d’accès par défaut, définissez une durée de vie de jeton d’accès par défaut statique à l’aide d’une durée de vie de jeton configurable (CTL).

La variation de durée de vie de jeton par défaut est appliquée aux organisations pour lesquelles l’évaluation continue de l’accès est activée. La variation de durée de vie des jetons par défaut est appliquée même si les organisations utilisent des stratégies de durée de vie de jeton configurable. 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 apparaît entre 1 heure et 2,5 heures, car le jeton est émis avec 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 établit une connexion interactive à la 59e minute (juste avant le dépassement de la fréquence de connexion), aucune invite d’informations d’identification ne s’affiche, car la connexion se produit en-deçà du seuil SIF. Si un nouveau jeton est émis, d’une durée de vie de 90 minutes, l’utilisateur ne voit pas d’invite d’informations d’identification pendant une heure et demie supplémentaire. En cas de tentative de renouvellement en mode silencieux de la durée de vie d’un jeton de 90 minutes, Azure AD exige une invite d’informations d’identification, car la longueur 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. Elles doivent uniquement accepter les jetons contenant leur revendication aud.
  • Les applications web confidentielles comme ASP.NET Core 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 ci-dessus ne s’applique, l’application ne tire pas parti de la validation du jeton et peut présenter un risque de sécurité et de fiabilité si des décisions sont prises en fonction de la validité du jeton. Les clients publics, comme les applications natives ou monopages, ne bénéficient pas de la validation des jetons, car l’application communique directement avec le fournisseur d’identité, de sorte que la protection SSL garantit la validité des jetons.

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, les jetons de Microsoft Graph ne sont pas validés en fonction de ces règles en raison de leur format propriétaire. 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. Par exemple, la version indépendante du client du document se trouve à l’adresse https://login.microsoftonline.com/common/.well-known/openid-configuration.

Le middleware (intergiciel) Azure AD 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 Azure AD, consultez Bibliothèques d’authentification.

Validation de la signature

Un jeton JWT contient trois segments séparés par le caractère . . Le premier segment est appelé l’en-tête, le second le corps et le troisième la signature. Le segment de signature peut être utilisé pour valider l’authenticité du jeton afin qu’il soit approuvé par l’application.

Les jetons émis par Azure AD sont signés à l’aide d’algorithmes de chiffrement asymétrique standard, tels 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 utilisée pour le valider.

À tout moment, Azure AD peut signer un jeton d’ID à l’aide de l’un des ensembles de paires de clés publique-privée. Étant donné qu’Azure AD alterne le jeu de clés possible de façon périodique, l’application doit être écrite 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 Azure AD, 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é. Le format JWK est décrit dans la RFC 7517. 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 dispose de clés de signature personnalisées après avoir utilisé la fonctionnalité de mappage des revendications, ajoutez un paramètre de requête appid contenant l’ID de l’application afin d’obtenir un jwks_uri qui pointe vers les informations de clé de signature de l’application qui doivent être utilisées pour la validation. Par exemple : https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contient un jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Autorisation basée sur les revendications

L’autorisation basée sur les revendications est déterminée par la logique métier de l’application. Certaines méthodes d’autorisation courantes sont listées ci-dessous.

Valider le jeton

Utilisez la revendication aud pour vérifier que l’utilisateur avait l’intention d’appeler l’application. Si l’identificateur de la ressource n’est pas dans la revendication aud, rejetez-le.

Valider l’autorisation utilisateur

Utilisez les revendications roles et wids pour vérifier que l’utilisateur est autorisé à appeler l’API. Par exemple, un administrateur peut avoir l’autorisation d’écrire dans l’API, mais pas un utilisateur normal. Vérifiez que le tid à l’intérieur du jeton correspond à l’ID de locataire utilisé pour stocker les données dans l’API.

Quand un utilisateur stocke des données dans l’API à partir d’un locataire, il doit se connecter au locataire pour accéder à ces données. N’autorisez jamais l’accès aux données d’un locataire à partir d’un autre locataire.

Utilisez la revendication amr pour vérifier que l’utilisateur a effectué la MFA. L’application de l’authentification multifacteur s’effectue à l’aide de l’accès conditionnel. Si des revendications roles ou groups sont demandées dans le jeton d’accès, vérifiez que l’utilisateur fait bien partie du groupe autorisé à effectuer cette action.

Pour les jetons récupérés à l’aide du flux implicite, interrogez Microsoft Graph pour ces données, car il est souvent trop grand pour être contenu dans le jeton.

N’utilisez pas les valeurs de revendication email ni upn pour déterminer si l’utilisateur figurant dans un jeton d’accès doit avoir accès aux données. Des valeurs de revendication mutables telles que celles-ci pouvant changer au fil du temps, elles ne sont ni sécurisées, ni fiables pour une autorisation.

Utilisez des valeurs de revendication immuables tid et sub ou oid en tant que clé combinée pour identifier de manière unique les données de l’API, et déterminer si un utilisateur doit être autorisé à accéder à ces données.

  • Bon : tid + sub
  • Mieux : tid + oid – l’oid étant cohérent entre les applications, un écosystème d’applications peut auditer l’accès des utilisateurs aux données.

N’utilisez pas d’identificateurs mutables intelligibles, tels que email ou upn, pour identifier des données de manière unique.

Valider la connexion de l’application

  • Utilisez la revendication scp pour vérifier que l’utilisateur a octroyé à l’application appelante l’autorisation d’appeler votre API.
  • Assurez-vous que le client appelant est autorisé à appeler votre API à l’aide de la revendication appid (pour les jetons v1.0) ou de la revendication azp (pour les jetons v2.0).
    • Vous devez uniquement valider ces revendications (appid, azp) si vous souhaitez restreindre votre API web pour qu’elle soit appelée uniquement par des applications prédéfinies (p. ex., des applications métier ou des API web appelées par des front-ends connus). Les API destinées à autoriser l’accès à partir de toute application appelante n’ont pas besoin de valider ces revendications.

Jetons d’utilisateur et d’application

Une application peut recevoir des jetons pour un utilisateur ou directement d’une application via le flux des informations d’identification du client. Ces jetons réservés aux applications indiquent que l’appel provient d’une application et qu’aucun utilisateur ne lui est associé. Ces jetons sont traités en grande partie de la même façon :

  • Utilisez roles pour afficher les autorisations qui ont été accordées au sujet du jeton.
  • Utilisez oid ou sub pour vérifier que le principal de service appelant est celui attendu.

Si l’application doit faire la distinction entre les jetons d’accès pour l’application uniquement et les jetons d’accès pour les utilisateurs, utilisez la revendication facultativeidtyp. Pour détecter les jetons d’accès à l’application uniquement, ajoutez la revendication idtyp au champ accessToken et vérifiez la valeur app. Les jetons d’ID et les jetons d’accès pour les utilisateurs ne contiennent pas la revendication idtyp.

Révocation de jetons

Les jetons d’actualisation peuvent être rendus non valides ou révoqués à tout moment, et ce pour diverses raisons, Les raisons entrent dans les catégories des délais d’expiration et des révocations.

Délais d’expiration des jetons

Quand une organisation utilise la configuration de la durée de vie des jetons, la durée de vie des jetons d’actualisation peut être modifiée. Il est prévu que certains jetons pourront ne pas être utilisés. Par exemple, l’utilisateur n’ouvre pas l’application pendant trois mois, puis le jeton expire. Les applications peuvent rencontrer des scénarios où le serveur de connexion rejette un jeton d’actualisation en raison de son âge.

  • MaxInactiveTime : si le jeton d’actualisation n’a pas été utilisé dans le délai défini par MaxInactiveTime, le jeton d’actualisation n’est plus valide.
  • MaxSessionAge : si MaxAgeSessionMultiFactor ou MaxAgeSessionSingleFactor ont été définis sur une valeur autre que la valeur par défaut (Until-revoked), une réauthentification est nécessaire après écoulement du délai défini dans MaxAgeSession*. Exemples :
    • Le locataire a un MaxInactiveTime de cinq jours et l’utilisateur est parti en congé pour une semaine. Par conséquent, Azure AD n’a pas reçu de nouvelle demande de jeton de la part de l’utilisateur depuis sept jours. La prochaine fois que l’utilisateur demandera un jeton, il s’apercevra que son jeton d’actualisation a été révoqué, et il devra entrer à nouveau ses informations d’identification.
    • Une application sensible a un MaxAgeSessionSingleFactor d’un jour. Si un utilisateur se connecte le lundi et le mardi (après 25 heures), il devra s’authentifier à nouveau.

Révocations de jetons

Les jetons d’actualisation peuvent être révoqués par le serveur en raison d’une modification des informations d’identification ou en raison d’une action d’utilisation ou d’administration. Les jetons d’actualisation se trouvent dans les classes de clients confidentiels et de clients publics.

Modifier Cookie basé sur un mot de passe Jeton basé sur un mot de passe Cookie non basé sur un mot de passe Jeton non basé sur un mots de passe Jeton client confidentiel
Le mot de passe expire Reste actif Reste actif Reste actif Reste actif Reste actif
Mot de passe modifié par l’utilisateur Révoqué Révoqué Reste actif Reste actif Reste actif
L’utilisateur effectue SSPR Révoqué Révoqué Reste actif Reste actif Reste actif
L’administrateur réinitialise le mot de passe Révoqué Révoqué Reste actif Reste actif Reste actif
L’utilisateur révoque ses jetons d’actualisation en utilisant PowerShell Révoqué Révoqué Révoqué Révoqué Révoqué
L’administrateur révoque tous les jetons d’actualisation d’un utilisateur en utilisant PowerShell Révoqué Révoqué Révoqué Révoqué Révoqué
Déconnexion unique (v1.0, v2.0) sur le web Révoqué Reste actif Révoqué Reste actif Reste actif

Non basée sur mot de passe

Une connexion non basée sur mot de passe est une connexion où l’utilisateur n’a pas saisi un mot de passe. Voici des exemples de connexions non basées sur mot de passe :

  • Utilisation de votre visage avec Windows Hello
  • Clé FIDO2
  • SMS
  • Voix
  • PIN

Pour plus d’informations sur les jetons d’actualisation principaux, consultez Jetons d’actualisation principaux.

Étapes suivantes