Partager via

Informations de référence sur les revendications facultatives

  • Article

Vous pouvez utiliser des revendications facultatives pour :

  • Sélectionnez les revendications à inclure dans les jetons de votre application.
  • Modifiez le comportement de certaines revendications retournées par la plateforme d’identités Microsoft dans les jetons.
  • Ajoutez et accédez aux revendications personnalisées pour votre application.

Bien que les revendications facultatives soient prises en charge dans les jetons de format v1.0 et v2.0 et les jetons SAML, elles fournissent la plupart de leur valeur lors du passage de la version 1.0 à la version 2.0. Dans la plateforme d’identités Microsoft, des tailles de jeton plus petites sont utilisées pour garantir des performances optimales par les clients. Par conséquent, 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 par application.

Type de compte Jetons v1.0 Jetons v2.0
Compte Microsoft personnel N/A Supporté
Compte Microsoft Entra Supporté Supporté

Ensemble de revendications facultatives v1.0 et v2.0

L’ensemble de revendications facultatives disponibles par défaut pour les applications à utiliser 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 les revendications demandées par l’application. Quelle que soit la façon dont le client accède à votre API, les données appropriées sont présentes dans le jeton d’accès utilisé pour s’authentifier auprès de votre API.

Note

La majorité de ces revendications peuvent être incluses dans les jetons JWT pour les jetons v1.0 et v2.0, mais pas dans les jetons SAML, sauf si elles sont notées dans la colonne Type de jeton. Les comptes de consommateurs prennent en charge un sous-ensemble de ces revendications, marqués dans la colonne Type d’utilisateur. La plupart des revendications répertoriées ne s’appliquent pas aux utilisateurs consommateurs (ils n’ont pas de locataire, donc tenant_ctry n’a pas de valeur).

Le tableau suivant répertorie le jeu de revendications facultatif v1.0 et v2.0.

Nom Description Type de jeton Type d’utilisateur Notes
acct État du compte d’utilisateurs dans le locataire JWT, SAML Si l’utilisateur est membre du locataire, la valeur est 0. S’ils sont invités, 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 peut effectuer. Les ID de contexte d’authentification peuvent être utilisés pour déclencher une demande d’authentification pas à pas à partir de votre application et de vos services. Souvent utilisé avec la revendication xms_cc.
auth_time Heure de la dernière authentification de l’utilisateur. JWT
ctry Pays/région de l’utilisateur JWT Cette revendication est retournée si elle est présente et que la valeur du champ est un code pays/région à deux lettres standard, tel que FR, JP, SZ, etc.
email Adresse e-mail signalée pour cet utilisateur JWT, SAML MSA, Microsoft Entra ID Cette valeur est incluse par défaut si l’utilisateur est invité dans le locataire. Pour les utilisateurs gérés (les utilisateurs à l’intérieur du locataire), il doit être demandé via cette revendication facultative ou, sur la version 2.0 uniquement, avec l’étendue OpenID. Cette valeur n’est pas garantie d’être correcte et est mutable au fil du temps . ne l’utilisez jamais pour l’autorisation ou pour enregistrer des données pour un utilisateur. Pour plus d’informations, consultez Valider que l’utilisateur a l’autorisation d’accéder à ces données. Si vous utilisez la revendication par e-mail pour l’autorisation, nous vous recommandons de 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 ces données directement à l’utilisateur, en utilisant cette revendication comme suggestion ou préremplie dans votre expérience utilisateur.
fwd Adresse IP JWT Ajoute l’adresse d’origine du client demandeur (lors de l’intérieur d’un réseau virtuel).
groups Mise en forme facultative pour les 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 d’application uniquement La valeur est app lorsque le jeton est un jeton d’application uniquement. 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+utilisateur.
login_hint Indicateur de connexion JWT MSA, Microsoft Entra ID Revendication d’indicateur de connexion opaque et fiable codée en base 64. Ne modifiez pas cette valeur. Cette revendication est la meilleure valeur à utiliser pour le paramètre OAuth login_hint dans tous les flux pour obtenir l’authentification unique. Il peut également être transmis entre les applications pour les aider à sSO silencieusement : l’application A peut également connecter un utilisateur, lire la revendication login_hint, puis envoyer la revendication et le contexte de locataire actuel à l’application B dans la chaîne de requête ou le fragment lorsque l’utilisateur sélectionne sur un lien qui les prend à l’application B. Pour éviter les problèmes de concurrence et de fiabilité, la revendication login_hintn’inclut pas le locataire actuel de l’utilisateur, et les valeurs par défaut sont le locataire domestique 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 demande de connexion. et passez les mêmes applications avec lesquelles vous collaborez. Cette revendication est destinée à être utilisée avec la fonctionnalité de login_hint existante de votre KIT de développement logiciel (SDK), mais elle est exposée.
tenant_ctry Pays/région du locataire de ressources JWT Identique à ctry sauf défini au niveau d’un locataire par un administrateur. Doit également être une valeur à deux lettres standard.
tenant_region_scope Région du locataire de ressource JWT
upn UserPrincipalName JWT, SAML Identificateur de l’utilisateur qui peut être utilisé avec le paramètre username_hint. N’est pas un identificateur durable pour l’utilisateur et ne doit pas être utilisé pour l’autorisation ou pour identifier de manière unique les informations utilisateur (par exemple, en tant que 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 Applications et API sécurisées en validant les revendications. Les utilisateurs qui se connectent avec un 'AUTRE ID de connexion ne doivent pas afficher 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 automatiquement incluse, vous pouvez la spécifier en tant que revendication facultative pour attacher d’autres propriétés pour modifier son comportement dans le cas de l’utilisateur invité. Vous devez utiliser la revendication login_hint pour login_hint utiliser : les identificateurs lisibles par l’homme comme UPN ne sont pas fiables.
verified_primary_email Source à partir de PrimaryAuthoritativeEmail de l’utilisateur JWT
verified_secondary_email Source à partir de SecondaryAuthoritativeEmail de l’utilisateur JWT
vnet Informations de spécificateur de réseau virtuel. JWT
xms_cc Fonctionnalités du client JWT Microsoft Entra ID Indique si l’application cliente qui a acquis le jeton est capable de gérer les défis liés aux revendications. Il est souvent utilisé avec la revendication acrs. Cette revendication est couramment utilisée dans les scénarios d’évaluation de l’accès conditionnel et de l’accès continu. Le serveur de ressources ou l’application de service que le jeton est émis pour contrôler la présence de cette revendication dans un jeton. Une valeur de cp1 dans le jeton d’accès est la méthode faisant autorité pour identifier qu’une application cliente est capable de gérer un défi de revendications. Pour plus d’informations, consultez défis liés aux revendications, demandes de revendications et fonctionnalités clientes.
xms_edov Valeur booléenne indiquant si le propriétaire du domaine de messagerie de l’utilisateur a été vérifié. JWT Un e-mail est considéré comme un domaine vérifié s’il appartient au locataire où réside le compte d’utilisateur et que l’administrateur du locataire a effectué la 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 à l’aide du 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 préféré JWT Pour les locataires multigéographiques, l’emplacement de données préféré est le code à trois lettres montrant la région géographique dans laquelle l’utilisateur se trouve. Pour plus d’informations, consultez la documentation Microsoft Entra Connect sur l’emplacement de données préféré.
xms_pl Langue par défaut de l’utilisateur JWT Langue par défaut de l’utilisateur, si elle est définie. Source de leur locataire domestique dans les scénarios d’accès invité. Mise en forme LL-CC ( »en-us« ).
xms_tpl Langue par défaut du locataire JWT Langue par défaut du locataire de ressource, si elle est définie. LL mis en forme (« en »).
ztdid ID de déploiement sans contact JWT Identité de l’appareil utilisée pour Windows AutoPilot.

Avertissement

N’utilisez jamais email ou upn valeurs de revendication pour stocker ou déterminer si l’utilisateur dans un jeton d’accès doit avoir accès aux données. Les valeurs de revendication mutables comme celles-ci peuvent changer au fil du temps, ce qui les rend non sécurisées et non fiables pour l’autorisation.

Ensemble de revendications facultatives spécifiques à v2.0

Ces revendications sont toujours incluses dans les jetons v1.0, mais pas incluses dans les jetons v2.0, sauf si elles sont demandées. Ces revendications s’appliquent uniquement aux jetons JWT (jetons d’ID et jetons d’accès).

Revendication JWT Nom Description Notes
ipaddr Adresse IP Adresse IP à partir de laquelle le client est connecté.
onprem_sid Identificateur de sécurité local
pwd_exp Heure d’expiration du mot de passe Nombre de secondes après l’heure de 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 les « jours de notification » dans la stratégie de mot de passe).
pwd_url Modifier l’URL du mot de passe URL que l’utilisateur peut visiter 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 les « jours de notification » dans la stratégie de mot de passe).
in_corp À l’intérieur du réseau d’entreprise Signale si le client se connecte à partir du réseau d’entreprise. Si ce n’est pas le cas, la revendication n’est pas incluse. En fonction des paramètres d’adresses IP approuvées dans l’authentification multifacteur.
family_name Nom Fournit le nom, le nom de famille ou le nom de famille de l’utilisateur tel que défini dans l’objet utilisateur. Par exemple, "family_name":"Miller". Pris en charge dans MSA et l’ID Microsoft Entra. Nécessite l’étendue profile.
given_name Prénom Fournit le premier ou le nom « donné » de l’utilisateur, tel qu’il est défini sur l’objet utilisateur. Par exemple, "given_name": "Frank". Pris en charge dans MSA et l’ID Microsoft Entra. Nécessite l’étendue profile.
upn Nom d’utilisateur principal Identificateur de l’utilisateur qui peut être utilisé avec le paramètre username_hint. N’est pas un identificateur durable pour l’utilisateur et ne doit pas être utilisé pour l’autorisation ou pour identifier de manière unique les informations utilisateur (par exemple, en tant que clé de base de données). Pour plus d’informations, consultez Applications et API sécurisées en validant les 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 afficher leur nom d’utilisateur principal (UPN). Utilisez plutôt la revendication preferred_username suivante pour afficher l’état de connexion à l’utilisateur. Nécessite l’étendue profile.

Ensemble de revendications facultatives spécifiques à v1.0

Certaines des améliorations du format de jeton v2 sont disponibles pour les applications qui utilisent le format de jeton v1, car elles permettent d’améliorer la sécurité et la fiabilité. Ces améliorations s’appliquent uniquement aux JWTs, et non aux jetons SAML.

Revendication JWT Nom Description Notes
aud Audience Toujours présent dans JWTs, mais dans les jetons d’accès v1, il peut être émis de différentes manières : n’importe quel URI appID, avec ou sans barre oblique de fin, et l’ID client de la ressource. Cette randomisation peut être difficile à coder lors de l’exécution de la validation des jetons. Utilisez additionalProperties pour cette revendication pour vous assurer qu’elle est toujours définie sur 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 préféré Fournit la revendication de nom d’utilisateur préférée dans les jetons v1. Cette revendication permet aux applications de fournir des indicateurs de nom d’utilisateur et d’afficher des noms d’affichage lisibles par l’homme, quel que soit leur type de jeton. Il est recommandé d’utiliser cette revendication facultative au lieu d’utiliser, upn ou unique_name. Jetons d’ID v1 et jetons d’accès

additionalProperties de revendications facultatives

Certaines revendications facultatives peuvent être configurées pour modifier la façon dont la revendication est retournée. Ces additionalProperties sont principalement utilisées pour faciliter la migration d’applications locales avec différentes attentes en matière de données. Par exemple, include_externally_authenticated_upn_without_hash aide avec les clients qui ne peuvent pas gérer les marques de hachage (#) dans l’UPN.

Nom de la propriété nom de additionalProperty Description
upn Peut être utilisé pour les réponses SAML et JWT, ainsi que pour les jetons v1.0 et v2.0.
include_externally_authenticated_upn Inclut l’UPN invité tel qu’il est stocké dans le locataire de ressource. Par exemple, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Identique à la liste précédente, sauf que les marques de hachage (#) sont remplacées par des traits de soulignement (_), par exemple foo_hometenant.com_EXT_@resourcetenant.com.
aud Dans les jetons d’accès v1, cette revendication est utilisée pour modifier le format de la revendication aud. Cette revendication n’a aucun effet dans les jetons v2 ou les jetons d’ID de version, où la revendication aud est toujours l’ID client. Utilisez cette configuration pour vous assurer que votre API peut effectuer plus facilement la validation de l’audience. Comme toutes les revendications facultatives qui affectent le jeton d’accès, la ressource dans la requête doit définir cette revendication facultative, car les ressources possèdent le jeton d’accès.
use_guid Émet l’ID client de la ressource (API) au format GUID en tant que revendication aud toujours au lieu d’être dépendante du runtime. Par exemple, si une ressource définit cet indicateur et 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 ce jeu 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 et l’ID client de la ressource.
idtyp Cette revendication est utilisée pour obtenir le type de jeton (application, utilisateur, appareil). Par défaut, il est émis uniquement pour les jetons d’application uniquement. Comme toutes les revendications facultatives qui affectent le jeton d’accès, la ressource dans la requête doit définir cette revendication facultative, car les ressources 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 le jeu de revendications idtyp, une API obtient uniquement la revendication pour les jetons d’application.

exemple de additionalProperties

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

Cet objet optionalClaims provoque le retour du jeton d’ID au client pour inclure une revendication de upn avec les autres informations relatives au locataire de base et au locataire de ressources. La revendication upn est modifiée uniquement dans le jeton si l’utilisateur est invité dans le locataire (qui utilise un autre fournisseur d’identité pour l’authentification).

Voir aussi

Étapes suivantes