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

  • Article

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 emailrevendication 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. Utilisé à la place de la revendication des groupes pour les jetons 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 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