Informations de référence sur les revendications de jeton d’ID

Article
10/25/2023

Les jetons d'ID sont des jetons web JSON (JWT). Les informations contenues dans les jetons d'ID v1.0 et v2.0 présentent des différences. La version est basée sur le point de terminaison à partir duquel le jeton a été demandé. Si les applications existantes utilisent probablement le point de terminaison Azure AD v1.0, les nouvelles applications doivent utiliser le point de terminaison v2.0.

v1.0 : https://login.microsoftonline.com/common/oauth2/authorize
v2.0 : https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Sauf indication contraire, toutes les revendications JWT répertoriées dans les sections ci-après apparaissent à la fois dans les jetons v1.0 et v2.0. Les jetons d’ID se composent d’un en-tête, d’une charge utile et d’une signature. L'en-tête et la signature permettent de vérifier l'authenticité du jeton, tandis que la charge utile contient les informations relatives à l'utilisateur qui sont demandées par votre client.

Revendications de l’en-tête

Le tableau ci-dessous indique les revendications d’en-tête présentes dans les jetons d’ID.

Revendication	Format	Description
`typ`	Chaîne : toujours « JWT »	Indique que le jeton est un jeton 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 la signature du jeton. Émis dans les jetons 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 v1.0 à des fins de compatibilité.

Revendications de la charge utile

Le tableau ci-dessous indique les revendications présentes par défaut dans la plupart des jetons d’ID (sauf indication contraire). Toutefois, votre application peut utiliser des revendications facultatives pour demander des revendications supplémentaires dans le jeton d'ID. Les revendications facultatives peuvent aller de la revendication groups à des informations telles que le nom de l'utilisateur.

Revendication	Format	Description
`aud`	Chaîne, GUID de l'ID d'application	Identifie le destinataire du jeton. Dans les jetons `id_tokens`, l'audience est l'ID attribué à votre application dans le portail Azure. Cette valeur doit être validée. Le jeton doit être rejeté s'il ne correspond pas à l'ID de votre application.
`iss`	Chaîne, URI d'un émetteur	Identifie l'émetteur, ou « serveur d'autorisation », qui construit et renvoie le jeton. Il identifie également le locataire pour lequel l’utilisateur a été authentifié. Si le jeton a été émis par le point de terminaison v2.0, 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`. Votre application doit utiliser la partie GUID de la revendication pour restreindre l’ensemble des clients qui peuvent se connecter à l’application, le cas échéant.
`iat`	int, timestamp UNIX	Indique quand l’authentification du jeton a eu lieu.
`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 (invités par exemple). Si la revendication n’est pas présente, cela signifie que 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), la revendication `idp` peut être « live.com » ou un URI STS contenant le locataire de compte Microsoft `9188040d-6c67-4c5b-b112-36a304b66dad`.
`nbf`	int, horodatage UNIX	Indique le délai avant lequel le jeton JWT ne peut pas être accepté pour être traité.
`exp`	int, horodatage UNIX	Indique le délai d’expiration à partir duquel le jeton JWT ne peut pas être accepté pour être traité. Dans certaines circonstances, une ressource peut rejeter le jeton avant l’expiration de ce délai. Par exemple, si une modification de l’authentification est nécessaire ou si une révocation de jeton a été détectée.
`c_hash`	String	Le hachage de code n’est inclus dans un jeton d’ID que si ce dernier est émis avec un code d’autorisation OAuth 2.0. Il peut servir à valider l’authenticité d’un code d’autorisation. Pour plus d'informations sur l'exécution de cette validation, consultez la spécification OpenID Connect. Cette revendication n’est pas retournée sur les jetons d’ID du point de terminaison /token.
`at_hash`	String	Le hachage de jeton d’accès n’est inclus dans un jeton d’ID que si ce dernier est émis du point de terminaison `/authorize` avec un jeton d’accès OAuth 2.0. Il peut servir à valider l’authenticité d’un jeton d’accès. Pour plus d'informations sur l'exécution de cette validation, consultez la spécification OpenID Connect. Cette revendication n’est pas retournée sur les jetons d’ID du point de terminaison `/token`.
`aio`	Chaîne opaque	Revendication interne utilisée pour enregistrer des données afin de réutiliser les jetons. Cette valeur doit être ignorée.
`preferred_username`	String	Nom d’utilisateur principal qui représente l’utilisateur. Il peut s’agir d’une adresse e-mail, d’un numéro de téléphone ou d’un nom d’utilisateur générique sans format spécifié. Sa valeur est mutable et peut changer au fil du temps. Dans la mesure où elle est mutable, cette valeur ne peut pas être utilisée pour prendre des décisions d’autorisation. Elle peut ê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. Présente uniquement dans les jetons v2.0.
`email`	String	Présente par défaut pour les comptes invités qui disposent d’une adresse e-mail. Votre application peut demander la revendication de courrier électronique pour les utilisateurs gérés (provenant du même locataire que la ressource) à l’aide de la `email` revendication facultative. Ce n’est pas garanti que cette valeur soit correcte, elle est mutable au fil du temps. Ne l’utilisez jamais à des fins d’autorisation ou pour enregistrer des données pour un utilisateur. Si vous avez besoin d’une adresse e-mail adressable dans votre application, demandez ces données directement auprès de l’utilisateur, en utilisant cette revendication comme une suggestion ou un préremplissage dans votre expérience utilisateur. Sur le point de terminaison v2.0, votre application peut également demander l’étendue OpenID Connect `email` : vous n’avez pas besoin de demander la revendication facultative et l’étendue pour obtenir la revendication.
`name`	String	La revendication `name` fournit une valeur explicite qui identifie le sujet du jeton. Il n’est pas certain que cette valeur soit unique. Elle peut être modifiée et ne doit être utilisée qu’à des fins d’affichage. L’étendue `profile` est requise afin de recevoir cette revendication.
`nonce`	String	Le nonce correspond au paramètre inclus dans la requête d’autorisation d’origine au fournisseur d’identité. Si ce n’est pas le cas, votre application doit rejeter le jeton.
`oid`	Chaîne, GUID	Identificateur immuable pour un objet ; dans ce cas, un compte d’utilisateur. Cet ID identifie de manière unique l’utilisateur entre les applications ; deux applications différentes se connectant au même utilisateur ont la même valeur dans la revendication `oid`. Microsoft Graph renvoie cet ID en tant que propriété `id` pour un compte d’utilisateur. `oid` permettant à plusieurs applications de faire correspondre des utilisateurs, l’étendue `profile` est requise afin de recevoir cette revendication. Si un utilisateur existe dans plusieurs locataires, il contient un ID d’objet différent dans chaque locataire. Ils sont considérés comme des comptes différents, même si l’utilisateur se connecte à chaque compte avec les mêmes informations d’identification. La revendication `oid` est un GUID qui ne peut pas être réutilisé.
`roles`	Tableau de chaînes	Ensemble des rôles attribués à l’utilisateur qui se connecte.
`rh`	Chaîne opaque	Revendication interne utilisée pour revalider des jetons. Cette valeur doit être ignorée.
`sub`	String	Objet des informations dans le jeton. Par exemple, l’utilisateur d’une application. Cette valeur est immuable et ne peut pas être réattribuée ou réutilisée. L’objet est un identificateur par paire qui est spécifique à un ID d’application. Si un utilisateur se connecte à deux applications différentes à l’aide de deux ID clients différents, ces applications reçoivent deux valeurs différentes pour la revendication de l’objet. Ceci peut être souhaitable ou non en fonction de vos exigences en matière d’architecture et de confidentialité.
`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`.
`unique_name`	String	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.
`ver`	Chaîne, 1.0 ou 2.0	Indique la version du jeton d’ID.
`hasgroups`	Boolean	Le cas échéant, toujours true, ce qui 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	Pour les requêtes 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" }` Pour plus d’informations, consultez Revendication de dépassement des groupes.

Utiliser des revendications pour identifier un utilisateur de manière fiable

Lors de l’identification d’un utilisateur, il est essentiel d’utiliser des informations qui restent constantes et uniques dans le temps. Les applications héritées utilisent parfois des champs tels que l’adresse e-mail, le numéro de téléphone ou l’UPN. Tous ces champs peuvent évoluer et être réutilisés au fil du temps. Par exemple, lorsqu'un employé modifie son nom ou reçoit une adresse e-mail correspondant à celle d'un employé précédent qui n'est plus présent. Votre application ne doit pas utiliser de données explicites pour identifier un utilisateur ; quelqu’un pourrait les lire et vouloir les modifier. Utilisez plutôt les revendications fournies par la norme OIDC, ou les revendications d’extension fournies par Microsoft (revendications sub et oid).

Pour stocker correctement les informations par utilisateur, utilisez sub ou oid seul (qui, comme des GUID, sont uniques), avec tid utilisé pour le routage ou le partitionnement, si nécessaire. Si vous avez besoin de partager des données entre les services, oid et tid sont préférables, car toutes les applications reçoivent les mêmes revendications oid et tid pour un utilisateur agissant dans un locataire. La revendication sub est une valeur par paire unique. La valeur repose sur une combinaison de destinataire du jeton, de locataire et d’utilisateur. Deux applications qui demandent des jetons d’ID pour un utilisateur reçoivent des revendications sub différentes, mais les mêmes revendications oid pour cet utilisateur.

Notes

N’utilisez pas la revendication idp pour stocker des informations sur un utilisateur dans une tentative de mettre en corrélation des utilisateurs parmi les locataires. Elle ne fonctionnera pas, car, par conception, les revendications oid et sub pour un utilisateur changent entre locataires pour s’assurer que des applications ne peuvent pas suivre des utilisateurs parmi les locataires.

Les scénarios d’invité, où un utilisateur est hébergé dans un locataire et s’authentifie dans un autre, doivent traiter l’utilisateur comme s’il s’agissait d’un tout nouvel utilisateur du service. Vos documents et privilèges dans un locataire ne doivent pas s’appliquer à un autre locataire. Cette restriction est importante pour éviter les fuites accidentelles de données entre les locataires et l’application des cycles de vie des données. Évincer un invité d’un locataire doit également supprimer son accès aux données qu’il a créées dans ce locataire.

Revendication de dépassement des groupes

Pour s’assurer que la taille du jeton ne dépasse pas les limites de taille d’en-tête HTTP, le nombre d’ID d’objets inclus dans la revendication groups est limité. 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), la revendication des groupes n’est pas incluse 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]"
        }
       }
     }
  ...
}

Étapes suivantes

En savoir plus sur les jetons d'identification utilisés dans Microsoft Entra ID.

Partager via