Émettre des claims personnalisés avec les attributs d'extension d’annuaire dans Microsoft Entra ID

Ce guide montre comment transmettre des données utilisateur personnalisées (par ex. identifiants de sponsor) aux applications lors de la connexion, en utilisant les attributs d’extension d’annuaire d’Entra ID. Vous apprendrez à enregistrer les attributs, les affecter aux utilisateurs, créer des claims conditionnels pour des groupes précis, contourner temporairement l’erreur de mappage des claims et tester l’émission des claims dans un jeton SAML/OIDC.

Contexte rapide

Les attributs d’extension d’annuaire permettent d’ajouter des paires clé/valeur propres à votre organisation dans l’objet Application d’Entra ID. Ces attributs peuvent ensuite être mappés en tant que claims dans les tokens SAML ou OIDC. Utile pour inclure des identifiants métiers (sponsor, rôle externe, contrat) uniquement pour des groupes sélectionnés.

Important : ne stockez pas de secrets ou de données sensibles non chiffrées dans ces attributs si leur exposition n’est pas contrôlée.

Étapes détaillées

Étape 1 — Enregistrer les attributs d’extension

Utilisez Graph Explorer ou une requête Microsoft Graph pour enregistrer deux attributs personnalisés (ex. sponsorid1 et sponsorid2) dans l’application cible.

Requête POST :

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

Request body example:
{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

Répétez pour sponsorid2. Après enregistrement, Microsoft renverra les noms complets au format :

• extension__sponsorid1
• extension__sponsorid2

Conservez ces noms exacts pour les étapes suivantes.

Étape 2 — Assigner les attributs aux utilisateurs

Mettez à jour l’objet utilisateur via Microsoft Graph pour lui attribuer la valeur d’extension.

Requête PATCH :

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

Request body:
{
  "extension__sponsorid1": "ABC123"
}

Répétez par utilisateur et par valeur (sponsorid1 ou sponsorid2). Vérifiez que vous avez les permissions Graph suffisantes (User.ReadWrite.All ou équivalent).

Étape 3 — Créer les claims dans l’application d’entreprise

Dans le portail Entra ID :

1. Entra ID > Enterprise applications > [Nom de l’application] > Single sign-on > Attributes & Claims
2. Cliquez sur Ajouter un nouveau claim
3. Donnez un nom (ex. sponsorClaim1)
4. Sous conditions du claim, sélectionnez Membre et choisissez le groupe cible
5. Pour l’attribut source, utilisez le nom d’attribut d’extension (ex. extension__sponsorid1)

Répétez la procédure pour le second groupe et le second attribut.

Étape 4 — Gérer l’erreur de mappage des claims

Si vous voyez l’erreur « Application requires custom signing key to customize claims », vous pouvez appliquer temporairement ce contournement :

Ouvrez le manifeste de l’app registration et mettez :

"acceptMappedClaims": true

Cela permet la personnalisation des claims sans clé de signature personnalisée. Notez que ceci peut avoir des implications de sécurité selon votre configuration : documentez et revoyez la solution avec votre équipe sécurité.

Étape 5 — Tester la configuration

Appelez le point d’autorisation et connectez-vous avec des utilisateurs appartenant aux groupes définis :

https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

Inspectez le jeton dans https://jwt.ms. Les utilisateurs des groupes devraient recevoir sponsorid1 ou sponsorid2 dans le token. Les autres utilisateurs ne recevront pas ces claims.

Bonnes pratiques et considérations

• Principe du moindre privilège : limitez l’accès à la lecture/écriture des attributs via des rôles Azure AD.
• Nommer clairement les attributs : inclure un préfixe organisationnel si vous avez plusieurs applications.
• Rotation et gouvernance : définissez qui peut modifier les mappings et quand.
• Sensibilité des données : évitez d’y placer des informations confidentielles non chiffrées.

Quand cette méthode échoue ou n’est pas adaptée

• Applications externes ne supportant pas les claims personnalisés : privilégiez une API backend pour enrichir le profil.
• Scénarios à très haute sensibilité (PII) : utilisez des jetons d’accès limités ou des mécanismes de consentement explicite.
• Si vous avez besoin d’émettre des claims basés sur des conditions complexes (calculs, historique), préférez une fonction d’émission côté service (claims transformation côté IdP ou proxy d’authentification).

Approches alternatives

• Utiliser un service de provisioning SCIM pour synchroniser des attributs directement dans l’application cible.
• Placer la logique d’enrichissement de claims dans un proxy d’authentification (ex. Azure AD B2C custom policies ou un API gateway).
• Pour SAML, configurer des transformations côté fournisseur d’identité si disponible.

Modèle mental rapide

• Entra ID = annuaire + moteur de mapping.
• Attribut d’extension = champ « propriétaire » attaché à l’app.
• Claim conditionnel = règle « si utilisateur est dans le groupe X, ajouter la valeur Y au token ».

Liste de vérification (checklist) pour l’administrateur

• Enregistrer les attributs d’extension et noter les noms complets.
• Assigner les valeurs aux utilisateurs via Graph.
• Configurer les claims conditionnels dans l’application d’entreprise.
• Modifier le manifeste si erreur de mappage (acceptMappedClaims).
• Tester avec des comptes de test pour chaque groupe.
• Documenter la configuration et les responsabilités.

Critères d’acceptation

• Les utilisateurs du groupe A reçoivent sponsorid1 dans leur token.
• Les utilisateurs du groupe B reçoivent sponsorid2 dans leur token.
• Les utilisateurs hors groupes ne reçoivent aucun claim sponsor.
• Les changements sont documentés et réversibles.

Runbook de test (exécution rapide)

1. Préparer 2 comptes test : userA ∈ groupeA, userB ∈ groupeB.
2. Mettre sponsorid1 pour userA et sponsorid2 pour userB via Graph.
3. Exécuter l’URL d’autorisation et se connecter en userA -> vérifier token.
4. Répéter pour userB.
5. Vérifier qu’un utilisateur non membre n’a pas le claim.
6. Revenir sur tout changement si anomalie.

Scénarios de rollback

• Annuler le changement du manifeste (remettre acceptMappedClaims à false si nécessaire).
• Supprimer ou vider l’attribut d’extension sur les utilisateurs concernés.
• Retirer le claim de l’application d’entreprise.

Points de sécurité et conformité

• GDPR/Protection des données : n’ajoutez que des données nécessaires. Documentez la finalité du traitement et la base légale.
• Journalisation : activez les logs d’audit pour les modifications Graph et les changements de manifest.
• Accès aux jetons : limitez qui peut voir ou stocker les jetons JWT contenant ces claims.

Exemples de tests d’acceptation

• Test 1 : userA (membre groupeA) obtient dans id_token la propriété sponsorClaim1 = “ABC123”.
• Test 2 : userB (membre groupeB) obtient sponsorClaim2 = “DEF456”.
• Test 3 : userC (hors groupes) n’a aucune propriété sponsor dans son id_token.

Fiche rapide (fact box)

• Étapes principales : 5
• Outils : Microsoft Graph, Entra ID portail, jwt.ms
• Points de vigilance : sécurité des attributs, permissions Graph, manifeste d’app

Rôles et responsabilités (résumé)

• Administrateur Entra ID : enregistre attributs, configure claims.
• Propriétaire d’application : valide le mapping et les besoins métiers.
• Responsable Sécurité/Conformité : approuve le stockage et la distribution des données.

Modèle décisionnel (Mermaid)

flowchart TD
  A[Démarrage] --> B{Attribuable par extension?}
  B -- Oui --> C[Enregistrer attributs via Graph]
  B -- Non --> D[Evaluer alternative: SCIM/API]
  C --> E[Assigner valeurs aux utilisateurs]
  E --> F[Configurer claims conditionnels]
  F --> G{Erreur mappage?}
  G -- Oui --> H[Mettre acceptMappedClaims:true]
  G -- Non --> I[Tester et valider]
  H --> I
  I --> J[Production]

Annexe : courte annonce (100–200 mots)

Nous avons ajouté la possibilité d’émettre des claims personnalisés par groupe via les attributs d’extension d’Entra ID. Cela permet d’injecter des identifiants métiers (par ex. sponsor) dans les tokens SAML/OIDC seulement pour les groupes autorisés. La mise en œuvre nécessite l’enregistrement d’attributs via Microsoft Graph, l’affectation des valeurs aux utilisateurs, et la configuration de claims conditionnels dans l’application d’entreprise. Un paramètre de manifeste (acceptMappedClaims) peut être activé temporairement si vous rencontrez une erreur liée à la clé de signature. Testez avec des comptes de recette et documentez les modifications. Contactez l’équipe identité pour assistance.

Résumé final

Les attributs d’extension d’annuaire sont un moyen simple et contrôlé d’ajouter des données contextuelles aux tokens d’authentification. Bien configurés, ils garantissent que seules les personnes et applications autorisées reçoivent les informations nécessaires au moment de la connexion.