Partager via

Informations de référence sur les revendications facultatives

  • Article

Vous pouvez utiliser des revendications facultatives pour :

  • Sélectionnez des revendications à inclure dans les jetons pour votre application.
  • Modifier le comportement de certaines revendications retournées par la plateforme d’identités Microsoft dans les jetons.
  • Ajouter et accéder à des revendications personnalisées pour votre application.

Si les revendications facultatives sont prises en charge dans les jetons aux formats v1.0 et v2.0 et les jetons SAML, elles révèlent l’essentiel de leur valeur lors du passage de v1.0 à v2.0. Dans la plateforme d’identité de Microsoft, des jetons de plus petite taille sont utilisés pour assurer une performance optimale des clients. Ainsi, plusieurs revendications précédemment incluses dans les jetons d’accès et d’ID ne sont plus présentes dans les jetons v2.0 et doivent être demandées spécifiquement pour chaque application.

Type de compte Jetons v1.0 Jetons v2.0
Compte Microsoft personnel N/A Prise en charge
Compte Microsoft Entra Prise en charge Prise en charge

Ensemble de revendications facultatives v1.0 et v2.0

L’ensemble de revendications facultatives disponible par défaut pour les applications est répertorié dans le tableau suivant. Vous pouvez utiliser des données personnalisées dans les attributs d’extension et les extensions d’annuaire pour ajouter des revendications facultatives pour votre application. Lorsque vous ajoutez des revendications au jeton d’accès, les revendications s’appliquent aux jetons d’accès demandés pour l’application (une API web), et non aux revendications requises par l’application. Quelle que soit la façon dont le client accède à votre API, les données correctes sont présentes dans le jeton d’accès qu’il utilise pour s’authentifier auprès de votre API.

Notes

La plupart de ces revendications peuvent figurer dans les jetons JWT pour les jetons v1.0 et v2.0, mais pas dans les jetons SAML, sauf indication contraire dans la colonne Type de jeton. Les comptes consommateur prennent en charge un sous-ensemble de ces revendications, indiqué dans la colonne Type d’utilisateur. La plupart des revendications répertoriées ne s’appliquent pas aux utilisateurs consommateurs (comme ils n’ont pas de locataire, tenant_ctry n’a donc pas de valeur).

Le tableau suivant répertorie l’ensemble de revendications facultatives v1.0 et v2.0.

Nom Description Type de jeton Type d’utilisateur Notes
acct Statut du compte utilisateur dans le locataire JWT, SAML Si l’utilisateur est membre du client, la valeur est 0. S’il est un invité, la valeur est 1.
acrs ID de contexte d’authentification JWT Microsoft Entra ID 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.
auth_time Heure de dernière authentification de l’utilisateur. JWT
ctry Pays/Région de l’utilisateur JWT Cette revendication est renvoyée si elle est présente et si la valeur du champ est un code de pays/région à deux lettres standard, tel que FR, JP, SZ, etc.
email Adresse e-mail indiquée pour cet utilisateur JWT, SAML MSA, Microsoft Entra ID Cette valeur est incluse par défaut si l’utilisateur est un invité du locataire. Pour les utilisateurs gérés (à l’intérieur du locataire), elle doit être demandée via cette revendication facultative ou, sur la version 2.0 uniquement, avec l’étendue OpenID. Cette valeur n’est pas garantie comme étant correcte, et est mutable dans le temps - ne l’utilisez jamais pour une autorisation ou pour sauvegarder des données pour un utilisateur. Pour plus d'informations, voir Valider que l'utilisateur a la permission d'accéder à ces données. Si vous utilisez les revendications par e-mail pour des autorisations, nous vous recommandons d’effectuer une migration pour passer à une revendication plus sécurisée. Si vous avez besoin d’une adresse e-mail adressable dans votre application, demandez cette donnée directement à l’utilisateur, en utilisant cette revendication comme une suggestion ou un préremplissage dans votre expérience utilisateur.
fwd Adresse IP JWT Ajoute l’adresse d’origine du client demandeur (quand il se trouve sur un réseau virtuel).
groups Mise en forme facultative des revendications de groupe JWT, SAML La revendication groups est utilisée avec le paramètre GroupMembershipClaims dans le manifeste de l’application, qui doit également être défini.
idtyp Type de jeton Jetons d’accès JWT Spécial : uniquement dans les jetons d’accès à l’application uniquement La valeur est app lorsque le jeton est un jeton uniquement de l’application. Cette revendication est la façon la plus précise pour une API de déterminer si un jeton est un jeton d’application ou un jeton d’application + un jeton d’utilisateur.
login_hint Indicateur de connexion JWT MSA, Microsoft Entra ID Une revendication d’indicateur de connexion opaque et fiable qui est encodée en base64. Ne modifiez pas cette valeur. Cette revendication est la meilleure valeur à utiliser pour le login_hint paramètre OAuth dans tous les flux pour obtenir l’authentification unique. Elle peut être transmise entre les applications pour les aider à utiliser l’authentification unique en mode silencieux, de même l’application A peut connecter un utilisateur, lire la revendication login_hint, puis envoyer la revendication et le contexte du locataire actuel à l’application B dans la chaîne de requête ou le fragment lorsque l’utilisateur sélectionne un lien qui le dirige vers l’application B. Pour éviter les conditions de concurrence et les problèmes de fiabilité, la login_hintn’inclut pas le locataire actuel pour l’utilisateur, et par défaut le locataire d’hébergement de l’utilisateur lorsqu’il est utilisé. Dans un scénario invité où l’utilisateur provient d’un autre locataire, un identificateur de locataire doit être fourni dans la requête de connexion. et passez le même aux applications avec lesquelles vous collaborez. Cette revendication est destinée à être utilisée avec les fonctionnalités existantes de votre kit de développement logiciel (SDK) login_hint, toutefois elle est exposée.
sid ID de session, utilisé pour la déconnexion de l’utilisateur après chaque session JWT Comptes personnels et Microsoft Entra.
tenant_ctry Pays/Région du locataire de la ressource JWT Identique à ctry sauf si défini au niveau du locataire par un administrateur. Doit également être une valeur standard à deux lettres.
tenant_region_scope Région du locataire de ressource. JWT
upn UserPrincipalName JWT, SAML Un identificateur pour l’utilisateur qui peut être utilisé avec le paramètre username_hint. Il ne s’agit pas d’un identifiant durable pour l’utilisateur et ne doit pas être utilisé pour l’autorisation ou pour identifier de manière unique les informations de l’utilisateur (par exemple, comme clé de base de données). Utilisez plutôt l’ID d’objet utilisateur (oid) comme clé de base de données. Pour plus d’informations, consultez Sécuriser les applications et les API par la validation des revendications. Les utilisateurs qui se connectent avec un autre ID de connexion ne doivent pas voir leur nom d’utilisateur principal (UPN). Utilisez plutôt les revendications de jeton d’ID suivantes pour afficher l’état de connexion à l’utilisateur : preferred_username ou unique_name pour les jetons v1 et preferred_username pour les jetons v2. Bien que cette revendication soit incluse automatiquement, vous pouvez la spécifier en tant que revendication facultative pour attacher d’autres propriétés afin de modifier son comportement en cas d’utilisateur invité. Vous devez utiliser la revendication login_hint pour l’utilisation login_hint. Les identificateurs lisibles explicites comme UPN ne sont pas fiables.
verified_primary_email Obtenu à partir du PrimaryAuthoritativeEmail de l’utilisateur JWT
verified_secondary_email Obtenu à partir du SecondaryAuthoritativeEmail de l’utilisateur JWT
vnet Informations sur le spécificateur de réseau virtuel. JWT
xms_cc Fonctionnalités du client JWT Microsoft Entra ID 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.
xms_edov Valeur booléenne indiquant si le propriétaire du domaine de messagerie de l’utilisateur a été vérifié. JWT Une adresse e-mail est considérée comme vérifiée par le domaine si elle appartient au tenant où réside le compte d’utilisateur et l’administrateur du tenant a effectué une vérification du domaine. En outre, l’e-mail doit provenir d’un compte Microsoft (MSA), d’un compte Google ou utilisé pour l’authentification en utilisant le flux de code secret à usage unique (OTP). Les comptes Facebook et SAML/WS-Fed n’ont pas de domaines vérifiés. Pour que cette revendication soit retournée dans le jeton, la présence de la revendication email est requise.
xms_pdl Emplacement de données par défaut JWT Pour les locataires multigéographiques, l’emplacement de données par défaut est le code à trois lettres indiquant la région géographique où se trouve l’utilisateur. Pour plus d’informations, consultez la documentation Microsoft Entra Connect sur l’emplacement préféré des données.
xms_pl Langue par défaut de l’utilisateur JWT La langue par défaut de l’utilisateur, si celle-ci a été définie. Dans les scénarios d’accès invité, provient du locataire de base. Au format langue-pays (« fr-fr »).
xms_tpl Langue par défaut du locataire JWT Langue par défaut du locataire de la ressource, si celle-ci est définie. Au format langue (« fr »).
ztdid ID de déploiement sans intervention JWT L’identité de l’appareil utilisée pour Windows AutoPilot.

Avertissement

N’utilisez jamais de valeurs de revendication email ou upn pour stocker ou déterminer si l’utilisateur d’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.

Ensemble de revendications facultatives spécifiques à v2.0

Ces revendications sont toujours incluses dans les jetons v1.0, mais elles ne sont pas incluses dans les jetons v2.0, sauf demande contraire. Ces revendications s’appliquent uniquement aux jetons web JSON (jetons d’ID et jetons d’accès).

Revendication JWT Nom Description Notes
ipaddr Adresse IP Adresse IP à partir de laquelle le client s’est connecté.
onprem_sid Identificateur de sécurité local
pwd_exp Heure d’expiration du mot de passe Le nombre de secondes après l’heure dans la revendication iat à laquelle le mot de passe expire. Cette revendication n’est incluse que lorsque le mot de passe expire bientôt (tel que défini par « jours de notification » dans la stratégie de mot de passe).
pwd_url Modifier l’URL de mot de passe URL à laquelle l’utilisateur peut accéder pour modifier son mot de passe. Cette revendication n’est incluse que lorsque le mot de passe expire bientôt (tel que défini par « jours de notification » dans la stratégie de mot de passe).
in_corp Dans le périmètre du réseau d’entreprise Indique si le client se connecte à partir du réseau d’entreprise. Dans le cas contraire, la revendication n’est pas incluse. Basé sur les adresses IP approuvées définies dans MFA.
family_name Nom Fournit le nom de famille de l’utilisateur, tel que défini sur l’objet utilisateur. Par exemple : "family_name":"Miller". Pris en charge dans MSA et Microsoft Entra ID. Nécessite l’étendue profile.
given_name Prénom Fournit le prénom de l’utilisateur, tel que défini sur l’objet utilisateur. Par exemple : "given_name": "Frank". Pris en charge dans MSA et Microsoft Entra ID. Nécessite l’étendue profile.
upn Nom d’utilisateur principal Un identificateur pour l’utilisateur qui peut être utilisé avec le paramètre username_hint. Il ne s’agit pas d’un identifiant durable pour l’utilisateur et ne doit pas être utilisé pour l’autorisation ou pour identifier de manière unique les informations de l’utilisateur (par exemple, comme clé de base de données). Pour plus d’informations, consultez Sécuriser les applications et les API par la validation des revendications. Utilisez plutôt l’ID d’objet utilisateur (oid) comme clé de base de données. Les utilisateurs qui se connectent avec un autre ID de connexion ne doivent pas voir leur nom d’utilisateur principal (UPN). Utilisez plutôt la revendication preferred_username suivante pour indiquer l’état de connexion à l’utilisateur. Nécessite l’étendue profile.

Ensemble de revendications facultatives spécifiques à v1.0

Certaines des améliorations apportées au format de jeton v2 sont disponibles pour les applications qui utilisent le format de jeton v1, car elles contribuent à développer la sécurité et la fiabilité. Ces améliorations s’appliquent uniquement aux jetons JWT, et non SAML.

Revendication JWT Nom Description Notes
aud Public visé Toujours présentes dans les jetons JWT, mais elles peuvent être émises de différentes manières dans les jetons d’accès v1 : tout URI appID, avec ou sans barre oblique de fin, ainsi que l’ID client de la ressource. Cette randomisation peut être difficile à coder lors de la validation du jeton. Utilisez additionalProperties pour cette revendication pour vous assurer qu’elle correspond toujours à l’ID client de la ressource dans les jetons d’accès v1. Jetons d’accès JWT v1 uniquement
preferred_username Nom d’utilisateur par défaut Indique la revendication de nom d’utilisateur par défaut dans les jetons v1. Les applications peuvent ainsi fournir plus facilement des indications de nom d’utilisateur et présenter des noms d’affichage lisibles par les utilisateurs, quel que soit leur type de jeton. Il est recommandé d’utiliser cette revendication facultative au lieu de upn ou unique_name. Jetons d’ID et jetons d’accès v1

additionalProperties des revendications facultatives

Certaines revendications facultatives peuvent être configurées pour modifier la façon dont la revendication est retournée. Ces additionalProperties servent principalement à faciliter la migration d’applications locales ayant des attentes différentes vis-à-vis des données. Par exemple, include_externally_authenticated_upn_without_hash aide avec les clients qui ne prennent pas en charge les marques de hachage (#) dans l’UPN.

Nom de la propriété Nom additionalProperty Description
upn Peut être utilisée pour les réponses SAML et JWT, ainsi que pour les jetons v1.0 et v2.0.
include_externally_authenticated_upn Inclut l’UPN de l’invité tel que stocké dans le locataire de ressource. Par exemple : foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Comme précédemment, sauf que les signes dièse (#) sont remplacés par des traits de soulignement (_), par exemple foo_hometenant.com_EXT_@resourcetenant.com.
aud Dans les jetons d’accès v1, cette revendication permet de modifier le format de la revendication aud. Cette revendication n’a aucun effet dans les jetons v2 et les jetons d’ID, des deux versions, où la revendication aud correspond toujours à l’ID client. Utilisez cette configuration pour que votre API puisse effectuer plus facilement la validation de l’audience. À l’instar de toutes les revendications facultatives qui affectent le jeton d’accès, la ressource indiquée dans la demande doit définir cette revendication facultative. Ce sont en effet les ressources qui possèdent le jeton d’accès.
use_guid Émet l’ID client de la ressource (API) au format GUID toujours sous forme de revendication aud au lieu d’être dépendant du runtime. Par exemple, si une ressource définit cet indicateur et que son ID client est 00001111-aaaa-2222-bbbb-3333cccc4444, toute application qui demande un jeton d’accès pour cette ressource reçoit un jeton d’accès avec aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Sans cet ensemble de revendications, une API peut obtenir des jetons avec une revendication aud de api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField ou toute autre valeur définie comme URI d’ID d’application pour cette API, ainsi que l’ID client de la ressource.
idtyp Cette revendication sert à obtenir le type de jeton (application, utilisateur, appareil). Par défaut, il n’est émis que pour les jetons d’application. À l’instar de toutes les revendications facultatives qui affectent le jeton d’accès, la ressource indiquée dans la demande doit définir cette revendication facultative. Ce sont en effet les ressources qui possèdent le jeton d’accès.
include_user_token Émet la revendication idtyp pour le jeton des utilisateurs. Sans cette propriété supplémentaire facultative pour l’ensemble de revendications idtyp, une API n’obtient que la revendication pour les jetons d’application.

Exemple additionalProperties

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Cet objet optionalClaims retourne au client le jeton d’ID pour y inclure une revendication upn avec d’autres informations sur le locataire d’accueil et le locataire de ressource. La revendication upn est uniquement Modifiée dans le jeton si l’utilisateur est un invité du locataire (qui utilise un fournisseur d’identité différent pour l’authentification).

Voir aussi

Étapes suivantes