Informations de référence sur les revendications de jeton d’accès

  • Article

Les jetons d’accès sont des jetons Web JSON (JWT). Les JWT contiennent les éléments suivants :

  • En-tête : fournit des informations sur la façon de valider le jeton, dont des informations sur le type du jeton et sa méthode de signature.
  • 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 pièce est séparée par un point (.) et codée séparément en Base 64.

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). Le jeton d’accès contient toujours suffisamment de revendications pour l’évaluation de l’accès.

La plateforme d’identités Microsoft utilise certaines revendications pour permettre de sécuriser la réutilisation des jetons. La description de Opaque indique que ces revendications ne sont pas destinées à la consommation 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 de la clé publique utilisée pour valider la 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 Considérations relatives aux autorisations
acrs Tableau de chaînes JSON Indique les ID de contexte d'authentification des opérations que le porteur est autorisé à effectuer. Les ID de contexte d'authentification peuvent être utilisés pour déclencher une demande d'authentification renforcée depuis votre application et vos services. Souvent utilisé avec la revendication xms_cc.
aud Chaîne, URI d’ID d’application ou GUID Identifie l’audience ciblée du jeton. 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. Cette valeur doit être validée. Rejetez le jeton si la valeur ne correspond pas au public concerné.
iss Chaîne, URI de service de jeton de sécurité (STS) Identifie le service d’émission de jeton de sécurité (STS) qui construit et retourne le jeton, ainsi que le locataire Microsoft Entra de l’utilisateur 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. Utilisez la valeur de iss si la revendication n’est pas présente. Pour les comptes personnels utilisés dans un contexte organisationnel (par exemple, un compte personnel invité dans un locataire Microsoft Entra), 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 Spécifie l’heure après laquelle le JWT peut être traité.
exp int, horodatage UNIX Indique le délai d’expiration avant lequel le jeton JWT peut être accepté pour traitement. Une ressource peut également rejeter le jeton avant cette heure. Le rejet peut se produire pour une modification requise de l’authentification ou lorsqu’un jeton est révoqué.
aio Chaîne opaque Revendication interne utilisée par Microsoft Entra ID 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 la méthode d’authentification de l’objet du jeton.
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 Microsoft Entra ID. appid peut être utilisé dans les décisions d’autorisation.
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 Microsoft Entra ID. azp peut être utilisé dans les décisions d’autorisation.
appidacr Chaîne, un 0, un 1 ou un 2, présente uniquement dans les jetons v1.0 Indique la méthode d’authentification du client. Pour un client public, la valeur est 0. Lorsque vous utilisez l’ID client et la clé secrète client, 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 la méthode d’authentification du client. Pour un client public, la valeur est 0. Lorsque vous utilisez l’ID client et la clé secrète client, 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é. Utilisez la valeur pour des indices sur le nom d’utilisateur et en tant que nom d’utilisateur dans une interface utilisateur lisible à l’œil. Pour recevoir cette revendication, utilisez l’étendue profile. Cette valeur étant mutable, ne l’utilisez pas pour prendre des décisions d’autorisation.
name String Fournit une valeur contrôlable de visu qui identifie le sujet du jeton. La valeur peut varier, elle est mutable et elle est destinée uniquement à des fins d’affichage. Pour recevoir cette revendication, utilisez l’étendue profile. N’utilisez pas cette valeur pour prendre des décisions d’autorisation.
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. Uniquement inclus pour les jetons utilisateur. L’application doit vérifier la validité de ces étendues et prendre des décisions d’autorisation en fonction de leur valeur.
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. Le flux d’informations d’identification client utilise cet ensemble d’autorisations au lieu des étendues d’utilisateur pour les jetons d’application. Pour les jetons utilisateur, cet ensemble de valeurs contient les rôles attribués de l’utilisateur pour l’application cible. Ces valeurs peuvent être utilisées pour la gestion des accès, par exemple, l’autorisation d’accès à une ressource.
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 Microsoft Entra. La propriété groupMembershipClaims du manifeste d’application configure cette revendication selon chaque application. Définissez la revendication sur All ou DirectoryRole. Ces valeurs peuvent être utilisées pour la gestion des accès, par exemple, l’autorisation d’accès à une ressource.
groups Tableau de GUID JSON Fournit les ID d’objet qui représentent les appartenances aux groupes du sujet. La propriété groupMembershipClaims du manifeste d’application configure cette revendication de groupe selon chaque application. Une valeur null exclut tous les groupes, une valeur SecurityGroup inclut les rôles d’annuaire et 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. Pour les autres flux, si le nombre de groupes auxquels l’utilisateur appartient dépasse 150 pour SAML et 200 pour JWT, alors Microsoft Entra ID 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. Ces valeurs peuvent être utilisées pour la gestion des accès, par exemple, l’autorisation d’accès à une ressource.
hasgroups Boolean Le cas échéant, toujours true, indique que l’utilisateur appartient à au moins un groupe. 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 Inclut un lien vers la liste complète des groupes pour l’utilisateur lorsque les demandes de jeton sont trop conséquentes pour le jeton. 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 Le principal associé au jeton. Par exemple, l’utilisateur d’une application. Cette valeur est non modifiable. Ne pas la réaffecter ou la réutiliser. L’objet est un identificateur par paire spécifique à un ID d’application spécifique. 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. L’utilisation des deux valeurs différentes dépend des exigences d’architecture et de confidentialité. Consultez également la revendication oid qui reste la même pour toutes les applications d’un même locataire. Cette valeur peut être utilisée pour effectuer des vérifications d’autorisation, comme lorsque le jeton est utilisé pour accéder à une ressource, et peut servir de clé dans les tables de base de données.
oid Chaîne, GUID L’identificateur non modifiable pour le demandeur, qui correspond à l’identité vérifiée de l’utilisateur ou du principal de service. 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é. Utilisez l’étendue profile pour recevoir cette revendication pour les utilisateurs, car oid permet à plusieurs applications de mettre les principaux en corrélation. Si un utilisateur existe dans plusieurs locataires, l’utilisateur contient un ID d’objet différent dans chaque locataire. Bien que l’utilisateur se connecte à chaque compte avec les mêmes informations d’identification, les comptes sont différents. Cette valeur peut être utilisée pour effectuer des vérifications d’autorisation, comme lorsque le jeton est utilisé pour accéder à une ressource, et peut servir de clé dans les tables de base de données.
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. Cette valeur doit être prise en compte en combinaison avec d’autres revendications dans les décisions d’autorisation.
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. Cette valeur peut être différente au sein d’un locataire et peut l’utiliser 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.
xms_cc Tableau de chaînes JSON Indique si l’application cliente ayant acquis le jeton peut gérer les défis liés aux revendications. Il est souvent utilisé avec claim acrs. Cette revendication est couramment utilisée dans les scénarios d’Accès conditionnel et d’Évaluation continue de l’accès. Le serveur de ressources ou l'application de service pour laquelle le jeton est émis contrôle la présence de cette revendication dans un jeton. Une valeur de cp1 dans le jeton d'accès est le moyen faisant autorité pour identifier qu'une application cliente est capable de gérer une contestation de revendications. Pour plus d’informations, consultez Contestation des revendications, demandes de revendications et fonctionnalités du client.

Remarque

Les revendications roles, groups, scp et wids ne constituent pas une liste exhaustive des façons dont une ressource peut autoriser un utilisateur ou une application, ni une liste exhaustive des autorisations accordées à l’appelant. La ressource cible peut utiliser une autre méthode pour autoriser l’accès à ses ressources protégées.

Revendication de dépassement des groupes

Microsoft Entra ID 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 qui dépasse la limite maximale (150 pour les jetons SAML, 200 pour les jetons JWT), Microsoft Entra ID 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.

Remarque

L’URL retournée est une URL Azure AD Graph (c’est à dire, graph.windows.net). Au lieu de s’appuyer sur cette URL, les services doivent plutôt utiliser la revendication facultative idtyp (qui identifie si le jeton est une application ou un jeton d’application+utilisateur) pour construire une URL Microsoft Graph pour interroger la liste complète des groupes.

Revendications de base v1.0

Les jetons v1.0 comprennent les revendications suivantes, le cas échéant, mais pas 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 Une URL avec laquelle les utilisateurs peuvent réinitialiser leurs mots de passe.
in_corp boolean Indique si le client se connecte à partir du réseau d’entreprise.
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. Utilisez-la uniquement à des fins d’affichage et pour fournir des indices de nom d'utilisateur dans des 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 l’utilisation dans l’authentification d’un jeton JWT autosigné avec un certificat X509 appartenant à un service.
otp Code secret à usage unique utilisant un e-mail ou un SMS.
fed Indique l’utilisation d’une assertion d’authentification fédérée (JWT ou SAML, par exemple).
wia Authentification Windows intégrée
mfa Indique l’utilisation de l’authentification multifacteur. Comprend d’autres méthodes d’authentification lorsque cette revendication est présente.
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 Indique qu’aucune authentification n’est terminée.

Étapes suivantes