Configurer et gérer des revendications facultatives dans des jetons d’ID, des jetons d’accès et des jetons SAML

Les jetons renvoyés par Microsoft Entra sont de petite taille afin de garantir des performances optimales pour les clients qui les demandent. Par conséquent, plusieurs revendications ne sont plus présentes par défaut dans le jeton et doivent être demandées spécifiquement pour chaque application.

Vous pouvez configurer des revendications facultatives pour votre application via l’interface utilisateur des applications ou le manifeste du centre d’administration Microsoft Entra.

Prerequisites

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Exécution du Démarrage rapide : Inscrire une application

Configurer les revendications facultatives dans votre application

1. Connectez-vous au Centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.
2. Accédez à Entra ID>Inscriptions d’application.
3. Choisissez l’application pour laquelle vous souhaitez configurer des revendications facultatives en fonction de votre scénario et du résultat souhaité.

L’objet optionalClaims déclare les revendications facultatives demandées par une application. Une application peut configurer des revendications facultatives qui sont renvoyées dans les jetons d’identification, les jetons d’accès et les jetons SAML 2. L’application peut configurer un ensemble différent de revendications facultatives à retourner dans chaque type de jeton.

Si cela est justifié par une revendication spécifique, vous pouvez également modifier le comportement de la revendication facultative à l’aide du champ additionalProperties.

Configurer des revendications facultatives d’extension d’annuaire

En plus de l’ensemble de revendications facultatives standard, vous pouvez configurer des jetons pour inclure des extensions Microsoft Graph. Pour plus d’informations, consultez Ajouter des données personnalisées à des ressources à l’aide d’extensions.

Les attributs d’extension de prise en charge des revendications et les extensions de répertoire sont disponibles en option. Cette fonctionnalité est utile pour joindre plus d’informations utilisateur utilisables par votre application. Par exemple, d’autres identifiants ou options de configuration importantes définies par l’utilisateur. Par conséquent, si le manifeste de votre application demande une extension personnalisée et qu’un utilisateur MSA se connecte à votre application, ces extensions ne sont pas retournées.

Mise en forme d’extension d’annuaire

Lors de la configuration des revendications facultatives d’extension d’annuaire à l’aide du manifeste d’application, utilisez le nom complet de l’extension (au format : extension_<appid>_<attributename>). <appid> est la version nettoyée de l’appId (ou Client ID) de l’application qui demande la revendication.

Dans les jetons JWT, ces revendications seront émises avec le format de nom suivant : extn.<attributename>. Dans les jetons SAML, ces revendications sont émises avec le format d’URI suivant : http://schemas.microsoft.com/identity/claims/extn.<attributename>

Configurer les revendications facultatives des groupes

Cette section couvre les options de configuration sous les revendications facultatives pour la modification des attributs de groupe utilisés dans les revendications de groupe, de l’ObjectId de groupe par défaut aux attributs synchronisés à partir du Windows Active Directory local. Vous pouvez configurer des revendications facultatives de groupe pour votre application via le portail Azure ou le manifeste de l’application. Les revendications facultatives de groupe sont émises uniquement dans le JWT pour les principaux d’utilisateur. Les entités de service ne sont pas incluses dans les revendications facultatives de groupe émises dans le JWT.

Suivez les étapes suivantes pour configurer les revendications facultatives de groupes à l’aide du portail Azure :

1. Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.
2. Dans Gérer, sélectionnez Configuration de jetons.
3. Sélectionnez Ajouter une revendication de groupe.
4. Sélectionnez les types de groupes à renvoyer (Groupes de sécurité ou Rôles d’annuaire, Tous les groupes et/ou Groupes attribués à l’application) :
   • L'option Groupes attribués à l'application ne comprend que les groupes attribués à l'application. L’option Groupes attribués à l’application est recommandée pour les grandes organisations en raison de la limite appliquée au nombre de groupes dans le jeton. Pour modifier les groupes attribués à l’application, sélectionnez l’application dans la liste Applications d’entreprise. Sélectionnez Utilisateurs et groupes, puis Ajouter un utilisateur/groupe. Sélectionnez le ou les groupes que vous souhaitez ajouter à l’application dans Utilisateurs et groupes.
   • L'option Tous les groupes comprend SecurityGroup, DirectoryRole et DistributionList, mais pas Groupes attribués à l'application.
5. Facultatif : sélectionnez les propriétés du type de jeton pour modifier la valeur de la revendication de groupe afin qu’elle contienne les attributs du groupe local, ou pour remplacer la revendication de groupe par une revendication de rôle.
6. Sélectionnez Enregistrer.

Suivez les étapes suivantes pour configurer les revendications facultatives des groupes via le manifeste de l’application :

1. Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.

2. Sous Gérer, sélectionnez Manifeste.

3. Ajoutez l’entrée suivante à l’aide de l’éditeur de manifeste :

   Les valeurs valides sont :

   • « All » (cette option comprend SecurityGroup, DirectoryRole et DistributionList)
   • « SecurityGroup »
   • « DirectoryRole »
   • « ApplicationGroup » (cette option comprend uniquement les groupes attribués à l'application)

   Par exemple :

   "groupMembershipClaims": "SecurityGroup"
   

   Par défaut, les ID d’objet de groupe sont émis dans la valeur de revendication de groupe. Pour modifier la valeur de revendication afin qu’elle contienne des attributs de groupe local, ou pour modifier le type de revendication en rôle, utilisez une configuration optionalClaims comme suit :

4. Définissez des revendications facultatives de configuration de nom de groupe.

   Si vous souhaitez que les groupes du jeton contiennent les attributs de groupe locaux dans la section des revendications facultatives, indiquez à quel type de jeton la revendication facultative doit être appliquée. Vous indiquez également le nom de la revendication facultative demandée et toute autre propriété souhaitée.

   Plusieurs types de jetons peuvent être répertoriés :

   • idToken pour le jeton d’ID d’OIDC ;
   • accessToken pour le jeton d’accès OAuth
   • Saml2Token pour les jetons SAML.

   Le type Saml2Token s’applique aux jetons aux formats SAML 1.1 et SAML 2.0.

   Pour chaque type de jeton pertinent, modifiez la revendication des groupes pour utiliser la section optionalClaims dans le manifeste. Le schéma optionalClaims se présente comme suit :

   {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
   }
   

   Schéma de revendications facultatives	Valeur
   name	Doit être groups
   source	Aucun affichage. Omettez ou spécifiez la valeur null.
   essential	Aucun affichage. Omettez ou spécifiez la valeur false.
   additionalProperties	Liste des autres propriétés. Les options valides sont sam_account_name, dns_domain_and_sam_account_name, netbios_domain_and_sam_account_name, emit_as_roles et cloud_displayname.

   Dans additionalProperties, un seul des sam_account_name, dns_domain_and_sam_account_name, netbios_domain_and_sam_account_name est requis. Si plusieurs options sont présentes, la première est utilisée et les autres ignorées. Vous pouvez également ajouter cloud_displayname pour afficher le nom d’affichage du groupe de clouds. Cette option fonctionne uniquement quand groupMembershipClaims a la valeur ApplicationGroup.

   Certaines applications requièrent des informations de groupe sur l’utilisateur dans la revendication de rôle. Pour remplacer la revendication de groupe par une revendication de rôle, ajoutez emit_as_roles à additionalProperties. Les valeurs de groupe sont émises dans la revendication de rôle.

   Si emit_as_roles est utilisé, tous les rôles d’application configurés qui sont attribués à l’utilisateur (ou à une application de ressources) ne figurent pas dans la revendication de rôle.

Les exemples suivants illustrent la configuration manifeste pour les revendications de groupe :

Émettre des groupes en tant que noms de groupe dans les jetons d’accès OAuth au format dnsDomainName\sAMAccountName.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Émettez les noms de groupe à retourner au format netbiosDomain\sAMAccountName comme revendication de rôles dans les jetons d’ID SAML et OIDC.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

Émettez des noms de groupes au format sam_account_name pour les groupes synchronisés locaux et nom cloud_display pour les groupes cloud dans les jetons d’ID SAML et OIDC pour les groupes affectés à l’application.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Exemple de revendications facultatives

Plusieurs options sont disponibles pour mettre à jour les propriétés de configuration d’identité d’une application afin d’activer et de configurer des revendications facultatives :

• Vous pouvez utiliser le portail Azure
• Vous pouvez utiliser le manifeste.
• Il est également possible d’écrire une application qui utilise l’API Microsoft Graph pour mettre à jour votre application. Le type OptionalClaims dans le guide de référence de l’API Microsoft Graph peut vous aider à configurer les revendications facultatives.

Dans l’exemple suivant, le portail Azure et le manifeste sont utilisés pour ajouter des revendications facultatives aux jetons d’accès, d’ID et SAML destinés à votre application. Différentes revendications facultatives sont ajoutées à chaque type de jeton que l’application peut recevoir :

• Les jetons d’ID contiennent l’UPN pour les utilisateurs fédérés au format complet (<upn>_<homedomain>#EXT#@<resourcedomain>).
• Les jetons d’accès que d’autres clients demandent pour cette application incluent la revendication auth_time.
• Les jetons SAML contiennent l’extension de schéma de répertoire skypeId (dans cet exemple, l’ID d’application pour cette application est ab603c56068041afb2f6832e2a17e237). Le jeton SAML expose l’ID Skype sous la forme extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configurer des revendications dans le portail Azure :

1. Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.
2. Dans Gérer, sélectionnez Configuration de jetons.
3. Sélectionnez Ajouter une revendication facultative, sélectionnez ensuite le type de jeton ID, puis upn dans la liste des revendications. Enfin, sélectionnez Ajouter.
4. Sélectionnez Ajouter une revendication facultative, sélectionnez ensuite le type de jeton Access, puis auth_time dans la liste des revendications. Enfin, sélectionnez Ajouter.
5. Dans l’écran de vue d’ensemble « Configuration du jeton », sélectionnez l’icône en forme de crayon à côté d’upn, sélectionnez ensuite le bouton bascule Authentifié en externe, puis sélectionnez Enregistrer.
6. Sélectionnez Ajouter une revendication facultative, puis le type de jeton SAML et enfin extn.skypeID dans la liste des revendications (applicable uniquement si vous avez créé un objet utilisateur Microsoft Entra appelé skypeID). Sélectionnez ensuite Ajouter.

Configurez les revendications dans le manifeste :

1. Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.

2. Sous Gérer, sélectionnez Manifeste pour ouvrir l’éditeur de manifeste inlined.

3. Vous pouvez modifier directement le manifeste à l’aide de cet éditeur. Le manifeste respecte le schéma de Application entity et met automatiquement en forme le manifeste une fois enregistré. Les nouveaux éléments sont ajoutés à la propriété optionalClaims.

   "optionalClaims": {
       "idToken": [
           {
               "name": "upn",
               "essential": false,
               "additionalProperties": [
                   "include_externally_authenticated_upn"
               ]
           }
       ],
       "accessToken": [
           {
               "name": "auth_time",
               "essential": false
           }
       ],
       "saml2Token": [
           {
               "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
               "source": "user",
               "essential": true
           }
       ]
   }
   

4. Quand vous avez terminé de mettre à jour le manifeste, sélectionnez Enregistrer pour l’enregistrer.

Limite

Une application peut émettre un maximum de dix attributs d’extension en tant que revendications facultatives.

Contenu associé

• Jetons d’accès
• Manifeste de l’application
• Jetons d’ID
• Référence facultative des revendications