Configurer des revendications facultatives

Article
06/10/2024

Les jetons retournés par Microsoft Entra sont conservés plus petits pour garantir des performances optimales par les clients qui les demandent. Par conséquent, plusieurs réclamations ne sont plus présentes dans le jeton par défaut et doivent être demandées spécifiquement pour chaque application.

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

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

Continuer avec l’interface utilisateur de l’application
Continuer avec le manifeste

Dans Gérer, sélectionnez Configuration de jetons.
Sélectionnez Ajouter une revendication facultative.
Sélectionnez le type de jeton que vous souhaitez configurer, par exemple Accès.
Sélectionnez les revendications facultatives à ajouter.
Sélectionnez Ajouter.

Sous Gérer, sélectionnez Manifeste. Un éditeur de manifeste web s’ouvre, vous permettant de modifier le manifeste. Si vous le souhaitez, vous pouvez sélectionner Télécharger et modifier localement le manifeste, puis utiliser Charger afin de l’appliquer de nouveau à votre application. Si le fichier ne contient pas de propriété optionalClaims, vous pouvez l’ajouter.

L’entrée suivante du manifeste de l’application ajoute les revendications facultatives auth_time, ipaddr et upn aux jetons d’ID, d’accès et SAML.
```
"optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}
```
Lorsque vous avez terminé, sélectionnez Enregistrer. Les revendications facultatives spécifiées sont désormais incluses dans les jetons de votre application.

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

Nom	Type	Description
`idToken`	Collection	Revendications facultatives retournées dans le jeton d’ID JWT.
`accessToken`	Collection	Revendications facultatives retournées dans le jeton d’accès JWT.
`saml2Token`	Collection	Revendications facultatives retournées dans le jeton SAML.

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

Nom	Type	Description
`name`	Edm.String	Nom de la revendication facultative.
`source`	Edm.String	Source (objet d’annuaire) de la revendication. Il existe des revendications prédéfinies et définies par l’utilisateur à partir des propriétés d’extension. Si la valeur source est null, la revendication est une revendication facultative prédéfinie. Si la valeur source est user, la valeur de la propriété name est la propriété d’extension à partir de l’objet utilisateur.
`essential`	Edm.Boolean	Si la valeur est true, la revendication spécifiée par le client est nécessaire afin de garantir une expérience d’autorisation fluide pour la tâche demandée par l’utilisateur final. La valeur par défaut est false.
`additionalProperties`	Collection (Edm.String)	Autres propriétés de la revendication. Si une propriété existe dans cette collection, elle modifie le comportement de la revendication facultative spécifiée dans la propriété name.

Configuration des revendications facultatives d’extension de répertoire

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.

Important

Les jetons d’accès sont toujours générés à l’aide du manifeste de la ressource, pas du client. Dans la requête ...scope=https://graph.microsoft.com/user.read..., la ressource est l’API Microsoft Graph. Le jeton d’accès est créé à l’aide du manifeste de l’API Microsoft Graph, et non du manifeste du client. La modification du manifeste de votre application n’entraîne jamais de changement au niveau des jetons pour l’API Microsoft Graph. Pour vérifier que vos modifications de accessToken sont effectives, demandez un jeton pour votre application, pas pour une autre application.

Les revendications facultatives prennent en charge les attributs d’extension et les extensions de répertoire. Cette fonctionnalité est utile pour joindre plus d’informations utilisateur utilisables par votre application. Par exemple, d’autres identificateurs ou des options de configuration importantes que l’utilisateur a définies. 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 renvoyé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 réclamation.

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 des revendications facultatives de groupes

Conseil

Les étapes décrites dans cet article peuvent varier légèrement en fonction du portail de départ.

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 groupes pour votre application par le biais du Portail Azure ou du manifeste de l’application. Les revendications facultatives de groupe sont émises uniquement dans le JWT pour les principaux d’utilisateur. Les principaux de service ne sont pas inclus dans les revendications facultatives de groupe émises dans le JWT.

Important

Le nombre de groupes émis dans un jeton est limité à 150 pour les assertions SAML et 200 pour JWT, y compris les groupes imbriqués. Pour plus d’informations sur les limites du groupe et les mises en garde importantes relatives aux revendications de groupe à partir d’attributs locaux, consultez Configurer des revendications de groupe pour les applications.

Effectuez les étapes suivantes pour configurer des revendications facultatives de groupes à l’aide du Portail Azure :

Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.
Dans Gérer, sélectionnez Configuration de jetons.
Sélectionnez Ajouter une revendication de groupe.
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.
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.
Sélectionnez Enregistrer.

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

Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.
Sous Gérer, sélectionnez Manifeste.
Ajoutez l’entrée suivante à l’aide de l’éditeur de manifeste :

Les valeurs valides sont les suivantes :
- « 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 des objets de groupe sont émis dans la valeur de la 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 la configuration optionalClaims comme suit :

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

Si vous souhaitez que les groupes dans le jeton contiennent les attributs des groupes locaux dans la section des revendications facultatives, précisez à quel type de jeton la revendication facultative doit s’appliquer. Vous spécifiez également le nom de la revendication facultative demandée et toutes les autres propriétés souhaitées.

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/OIDC ;
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 de 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`	Non utilisé. Omettez ou spécifiez la valeur null.
`essential`	Non utilisé. 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 le point additionalProperties, un seul des points 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 émettre le nom d’affichage du groupe cloud. Cette option fonctionne uniquement si groupMembershipClaims est réglé sur ApplicationGroup.

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

Si emit_as_roles est utilisé, les rôles d’application configurés auxquels l’utilisateur est affecté ne sont pas dans la revendication de rôle.

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

Émettez 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 à renvoyer 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 demandés par d’autres clients 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). Les jetons SAML exposent l’ID Skype en tant que extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configurez les revendications dans le Portail Azure :

Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.
Dans Gérer, sélectionnez Configuration de jetons.
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.
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.
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.
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 :

Sélectionnez l’application pour laquelle vous souhaitez configurer des revendications facultatives.
Sous Gérer, sélectionnez Manifeste pour ouvrir l’éditeur de manifeste inlined.

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
        }
    ]
}

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

Voir aussi

Étapes suivantes

En savoir plus sur les jetons et les revendications dans la Plateforme d'identités Microsoft.

Partager via