Partager via

Forum aux questions sur l’approvisionnement entrant piloté par les API

  • Article

Cet article répond les questions du Forum aux Questions (FAQ) sur l’approvisionnement entrant piloté par les API.

Quelle est la différence entre la nouvelle API /bulkUpload d’approvisionnement entrant et l’API d’utilisateurs de MS Graph ?

Il existe des différences importantes entre l’API /bulkUpload d’approvisionnement et le point de terminaison de l’API d’utilisateurs de MS Graph.

  • Format de charge utile : le point de terminaison de l’API d’utilisateurs de MS Graph attend la réception des données au format OData. La requête du format de charge utile pour la nouvelle API /bulkUpload d’approvisionnement entrant utilise des constructions de schéma SCIM. Lorsque vous appelez cette API, définissez l’en-tête « Content-Type » sur application/scim+json.
  • Résultat final de l’opération :
    • Lorsque les données d’identité sont envoyées au point de terminaison de l’API MS Graph Users, elles sont immédiatement traitées et une opération Créer/Mettre à jour/Supprimer a lieu sur le profil utilisateur Microsoft Entra.
    • Les données de requête envoyées à l’API de provisionnement /bulkUpload sont traitées de manière asynchrone par le service de provisionnement Microsoft Entra. La tâche de provisionnement applique les règles de cadrage, le mappage d'attributs et la transformation configurés par l'administrateur informatique. Cela lance une opération Create/Update/Delete sur le profil utilisateur Microsoft Entra ou le profil utilisateur AD sur site.
  • L'administrateur informatique conserve le contrôle : grâce au provisionnement entrant piloté par API, l'administrateur informatique a plus de contrôle sur la manière dont les données d'identité entrantes sont traitées et mappées aux attributs Microsoft Entra. Ils peuvent définir des règles d’étendue pour exclure certains types de données d’identité (par exemple, les données du prestataire) et utiliser des fonctions de transformation pour dériver de nouvelles valeurs avant de définir les valeurs d’attribut sur le profil utilisateur.

L’API /bulkUpload d’approvisionnement entrant est-elle un point de terminaison SCIM standard ?

L’API /bulkUpload d’approvisionnement entrant de MS Graph utilise le schéma SCIM dans la requête de la charge utile mais il ne s’agit pas d’un point de terminaison d’API SCIM standardisé. Voici pourquoi.

En règle générale, un point de terminaison de service SCIM traite les requêtes HTTP (POST, PUT, GET) avec la charge utile SCIM et les traduit en opérations respectives (créer, mettre à jour, rechercher) dans le stockage d’identités. Le point de terminaison de service SCIM charge de spécifier la sémantique de l’opération, qu’il s’agisse de créer/mettre à jour/supprimer une identité, sur le client d’API SCIM. Ce mécanisme fonctionne bien pour les scénarios dans lesquels le client d’API sait quelle opération il souhaite effectuer pour les utilisateurs dans le stockage d’identités.

L’approvisionnement /bulkUpload entrant de MS Graph est conçu pour gérer un scénario d’intégration d’identité d’entreprise différent mis en forme par trois exigences uniques :

  1. Possibilité de traiter des enregistrements en bloc de manière asynchrone (par exemple, traiter plus de 50 000 enregistrements)
  2. Possibilité d’intégrer n’importe quel attribut d’identité dans la charge utile (par exemple, costCenter, pay grade, badgeId)
  3. Prendre en charge les clients d’API qui ne connaissent pas la sémantique des opérations. Ces clients sont des clients d’API non-SCIM qui ont uniquement accès aux données sources brutes (par exemple, les enregistrements dans un fichier CSV, une table SQL ou des enregistrements RH). Ces clients ne disposent pas de la capacité de traitement pour lire chaque enregistrement et déterminer la sémantique d’opération Create/Update/Delete dans le stockage d’identités.

L'objectif principal de l'API de provisionnement entrant/bulkUpload de MS Graph est de permettre aux clients d'envoyer n'importe quelles données d'identité (par exemple, costCenter, pay grade, badgeId) à partir de n'importe quelle source de données d'identité (par exemple, CSV/SQL/HR) pour un traitement éventuel par Service de provisionnement Microsoft Entra. Le service de provisionnement Microsoft Entra consomme les données de charge utile en masse reçues sur ce point de terminaison, applique les règles de mappage d'attributs configurées par l'administrateur informatique et détermine si la charge utile de données mène à une opération (Créer, Mettre à jour, Activer, Désactiver) dans le magasin d'identités cible (Identifiant Microsoft Entra / AD sur site).

L’API /bulkUpload d’approvisionnement prend-elle en charge les domaines Active Directory local en tant que cible ?

Oui, l’API d’approvisionnement prend en charge les domaines AD locaux en tant que cible.

Comment obtenir le point de terminaison de l’API /bulkUpload pour notre application d’approvisionnement ?

L'API /bulkUpload est disponible uniquement pour les applications du type : « Approvisionnement entrant piloté par API vers Microsoft Entra ID » et « Approvisionnement entrant piloté par API vers Active Directory sur site ». Vous pouvez récupérer le point de terminaison d’API unique pour chaque application d’approvisionnement à partir de la page d’accueil du panneau approvisionnement. Dans le panneau Statistiques à ce jour>Afficher les informations techniques et copiez l’URL du point de terminaison de l’API d’approvisionnement.

Il est au format :

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Comment effectuer une synchronisation complète à l’aide de l’API /bulkUpload d’approvisionnement ?

Pour effectuer une synchronisation complète, utilisez votre client d’API pour envoyer les données de tous les utilisateurs de votre source approuvée au point de terminaison de l’API en tant que requête en bloc. Une fois que vous avez envoyé toutes les données au point de terminaison de l’API, le cycle de synchronisation suivant traite tous les enregistrements d’utilisateur et vous permet de suivre la progression en utilisant le point de terminaison d’API des journaux d’approvisionnement.

Comment effectuer la synchronisation delta à l’aide de l’API /bulkUpload d’approvisionnement ?

Pour effectuer une synchronisation delta, utilisez votre client d’API pour envoyer uniquement des informations sur les utilisateurs dont les données ont changé dans la source approuvée. Une fois que vous avez envoyé toutes les données au point de terminaison de l’API, le cycle de synchronisation suivant traite tous les enregistrements d’utilisateur et vous permet de suivre la progression en utilisant le point de terminaison d’API des journaux d’approvisionnement.

Comment fonctionne l’approvisionnement automatique ?

Utilisez uniquement l’option Redémarrer l’approvisionnement si nécessaire. Fonctionnement de l’opération :

Scénario 1 : Lorsque vous cliquez sur le bouton Redémarrer l’approvisionnement et que lâ tâche est en cours d’exécution, celui-ci continue de traiter les données existantes déjà indexées. L’opération redémarrer l’approvisionnement n’interrompt pas un cycle existant. Dans le cycle suivant, le service d’approvisionnement efface les entiercements et sélectionne la nouvelle requête en bloc pour traitement.

Scénario 2 : Lorsque vous cliquez sur le bouton Redémarrer l’approvisionnement et que la tâche n’est pas en cours d’exécution, le moteur d’approvisionnement supprimer définitivement les données chargées avant le redémarrage, efface les entiercements et traite uniquement les nouvelles données entrantes.

Comment créer des utilisateurs à l’aide du point de terminaison de l’API /bulkUpload d’approvisionnement ?

Voici comment la tâche d’approvisionnement associée au point de terminaison de l’API /bulkUpload traite les charges utiles utilisateur entrantes :

  1. La tâche récupère le mappage d'attributs pour la tâche de provisionnement et prend note de la paire d'attributs correspondante (par défaut, l'attribut API externalId est utilisé pour correspondre avec employeeId à Microsoft Entra ID).
  2. Vous pouvez modifier cette paire d’attributs correspondante par défaut.
  3. La tâche extrait chaque opération présente dans la charge utile de requête en bloc.
  4. Le travail vérifie l'identifiant correspondant à la valeur dans la requête (par défaut l'attribut externalId) et l'utilise pour vérifier s'il existe un utilisateur dans Microsoft Entra ID avec une valeur employeeId correspondante.
  5. Si la tâche ne trouve pas d’utilisateur correspondant, elle applique les règles de synchronisation et crée un utilisateur dans le répertoire cible.

Pour vous assurer que les bons utilisateurs sont créés dans Microsoft Entra ID, définissez la bonne paire d'attributs correspondants dans votre mappage qui identifie de manière unique les utilisateurs dans votre source et Microsoft Entra ID.

Comment générer des valeurs uniques pour UPN ?

Le service d’approvisionnement ne permet pas de vérifier pour les doublons userPrincipalName (UPN) et de gérer les conflits. Si la règle de synchronisation par défaut pour l’attribut UPN génère une valeur UPN existante, l’opération de création de l’utilisateur échoue.

Voici quelques options que vous pouvez envisager pour générer des UPN uniques :

  1. Ajoutez la logique pour la génération d’UPN unique dans votre client d’API.
  2. Mettez à jour la règle de synchronisation pour l’attribut UPN afin d’utiliser la fonction RandomString et définissez le paramètre de mappage d’application sur On object creation only. Exemple :

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. Si vous approvisionnez pour Active Directory local, vous pouvez utiliser la fonction SelectUniqueValue et définir le paramètre de mappage d’application sur On object creation only.

Comment envoyer davantage d’attributs RH au point de terminaison de l’API /bulkUpload d’approvisionnement ?

Par défaut, le point de terminaison d’API prend en charge le traitement de tout attribut qui fait partie du schéma de l’utilisateur principal SCIM et de l’utilisateur d’entreprise. Si vous souhaitez envoyer plus d'attributs, vous pouvez étendre le schéma de l'application de provisionnement, mapper les nouveaux attributs aux attributs Microsoft Entra et mettre à jour la requête groupée pour envoyer ces attributs. Reportez-vous au didacticiel Étendre le provisionnement piloté par l’API pour synchroniser les attributs personnalisés.

Comment exclure certains utilisateurs du flux d’approvisionnement ?

Vous pouvez avoir un scénario dans lequel vous souhaitez envoyer tous les utilisateurs au point de terminaison d’API, mais intégrer uniquement certains utilisateurs dans le flux d’approvisionnement et exclure le reste.

Vous pouvez y parvenir à l’aide du filtre d’étendue. Dans la configuration de l’application d’approvisionnement, vous pouvez définir une étendue d’objet source et exclure certains utilisateurs du traitement à l’aide d’une « règle d’inclusion » (par exemple, traiter uniquement les utilisateurs dont le département EST ÉGAL aux ventes) ou une « règle d’exclusion » (par exemple, exclure les utilisateurs appartenant aux ventes, donc département PAS ÉGAL aux Sales).

Voir Étendue des utilisateurs ou des groupes à approvisionneravec des filtres d’étendue.

Comment mettre à jour les utilisateurs à l’aide du point de terminaison de l’API /bulkUpload d’approvisionnement ?

Voici comment la tâche d’approvisionnement associée au point de terminaison de l’API /bulkUpload traite les charges utiles utilisateur entrantes :

  1. La tâche de provisionnement récupère le mappage d'attributs pour la tâche de provisionnement et prend note de la paire d'attributs correspondante (par défaut, l'attribut API externalId est utilisé pour faire la correspondance avec employeeId dans Microsoft Entra ID). Vous pouvez modifier cette paire d’attributs correspondante par défaut.
  2. La tâche extrait les opérations de la charge utile de requête en bloc.
  3. Le travail vérifie l'identifiant de correspondance de valeur dans la requête SCIM (par défaut : attribut API externalId) et l'utilise pour vérifier s'il existe un utilisateur dans Microsoft Entra ID avec une valeur employeeId correspondante.
  4. Si la tâche trouve un utilisateur correspondant, il applique les règles de synchronisation et compare les profils source et cible.
  5. Si la tâche détermine que certaines valeurs ont changé, il met à jour l’enregistrement d’utilisateur correspondant dans le répertoire.

Pour vous assurer que les bons utilisateurs sont mis à jour dans Microsoft Entra ID, assurez-vous de définir la bonne paire d'attributs correspondants dans votre mappage qui identifie de manière unique les utilisateurs dans votre source et Microsoft Entra ID.

Pouvons-nous créer plusieurs applications qui prennent en charge l’approvisionnement entrant piloté par l’API ?

Oui, vous pouvez. Voici quelques scénarios qui peuvent nécessiter plusieurs applications d’approvisionnement :

Scénario 1 : Supposons que vous disposez de trois sources de données approuvées : une pour les employés, une pour les prestataires et une pour les fournisseurs. Vous pouvez créer trois applications d’approvisionnement distinctes, une pour chaque type d’identité avec son propre mappage d’attributs distinct. Chaque application d’approvisionnement a un point de terminaison d’API unique, et vous pouvez envoyer les charges utiles respectives à chaque point de terminaison.

Vous pouvez récupérer le point de terminaison d’API unique pour chaque tâche à partir de la page d’accueil du panneau approvisionnement. Accédez à l’option Statistiques à ce jour>Afficher les informations techniques, ensuite copiez l’URL du point de terminaison de l’API d’approvisionnement .

Scénario 2 : Supposons que vous ayez plusieurs sources de vérité, chacune avec son propre ensemble d’attributs. Par exemple, les RH fournissent des attributs d’informations sur le travail (par exemple jobTitle, employeeType) et le système Badging fournit des attributs d’informations de badge (par exemple badgeId, qui sont représentés à l’aide d’un attribut d’extension). Dans ce scénario, vous pouvez configurer deux applications d’approvisionnement :

  • Approvisionnement de l’application n°1 qui reçoit des attributs de votre source RH et crée l’utilisateur.

  • Approvisionnement de l’application n°2 qui reçoit les attributs du système Badging et met uniquement à jour les attributs utilisateur. Le mappage d’attributs dans cette application est limité aux attributs Informations de badge et seule la mise à jour est activé sous actions de l’objet cible.

  • Les deux applications utilisent la même paire d’identificateurs correspondants (externalId<->employeeId)

Comment traiter les terminaisons à l’aide du point de terminaison de l’API /bulkUpload ?

Pour traiter les résiliations, identifiez un attribut dans votre source qui sera utilisé pour définir l'indicateur accountEnabled dans Microsoft Entra ID. Si vous approvisionnez pour Active Directory local, mappez cet attribut source à l’attribut accountDisabled .

Par défaut, la valeur associée à l’attribut active du schéma SCIM Core User détermine l’état du compte de l’utilisateur dans le répertoire cible.

Si l’attribut a la valeur true, la règle de mappage par défaut active le compte. Si l’attribut a la valeur false, la règle de mappage par défaut désactive le compte.

Comment pouvons-nous empêcher la désactivation/suppression accidentelle d’utilisateurs ?

Pour éviter des suppressions accidentelles et les récupérer, nous vous recommandons de configurer le seuil de suppression accidentelle dans l’application d’approvisionnement et d’activer la corbeille Active Directory locale. Dans le panneau Mappage d’attributs de votre application d’approvisionnement, sous Actions d’objet cible, désactivez l’opération Delete.

Récupération de comptes supprimés

  • Si le répertoire cible de l’opération est Microsoft Entra ID, l’utilisateur correspondant est supprimé de manière logicielle. L’utilisateur est affiché sur la page Utilisateurs supprimés du Centre d’administration Microsoft Entra pendant 30 jours et peut être restauré durant cette période.
  • Si le répertoire cible de l’opération est Active Directory local, l’utilisateur correspondant est alors supprimé de manière définitive. Si la Corbeille Active Directory est activée, vous pouvez restaurer l’objet utilisateur AD local supprimé.

Devons-nous envoyer tous les utilisateurs du système RH à chaque requête ?

Non, vous n’avez pas besoin d’envoyer tous les utilisateurs du système RH / « source de vérité » à chaque requête. Envoyez simplement les utilisateurs que vous souhaitez créer ou mettre à jour.

L’API prend-elle en charge toutes les actions HTTP (GET/POST/PUT/PATCH) ?

Non, le point de terminaison de l’API /bulkUpload d’approvisionnement prend uniquement en charge l’action HTTP POST.

Si je souhaite mettre à jour un utilisateur, dois-je envoyer une requête PUT/PATCH ?

Non, le point de terminaison d’API ne prend pas en charge la requête PUT/PATCH. Pour mettre à jour un utilisateur, envoyez les données associées à l’utilisateur dans la charge utile de requête en bloc POST.

Le tâche d’approvisionnement qui traite les données reçues par le point de terminaison d’API détecte automatiquement si l’utilisateur reçu dans la charge utile de requête POST doit être créé/mis à jour/activer/désactivé en fonction des règles de synchronisation configurées. En tant que client d’API, vous n’avez pas besoin d’effectuer d’autres étapes si vous souhaitez mettre à jour un profil utilisateur.

Comment l’écriture différée est-elle prise en charge ?

L’API actuelle prend uniquement en charge les données entrantes. Voici quelques options à considérer pour mettre en œuvre la réécriture d'attributs tels que l'e-mail/le nom d'utilisateur/le téléphone générés par Microsoft Entra ID, que vous pouvez renvoyer au système RH :

  • Option 1 : connectivité SCIM au point de terminaison/service proxy de RH qui met à jour à son tour la source RH

    • Si le système d'enregistrement fournit un point de terminaison SCIM pour les mises à jour des utilisateurs, vous pouvez créer une application SCIM personnalisée dans la galerie d'applications de l'entreprise et configurer l’approvisionnement comme indiqué.
    • Si le système d’enregistrement ne fournit pas de point de terminaison SCIM, explorez la possibilité de configurer un service SCIM proxy, qui reçoit la mise à jour et propage la modification au système RH.

  • Option 2 – Utiliser le connecteur Microsoft Entra ECMA pour le scénario de réécriture

    • En fonction des besoins du client, déterminez si l’un des connecteurs ECMA peut être utilisé (PowerShell / SQL / Web Services).

  • Option 3 : utiliser la tâche d’extension personnalisée workflows de cycle de vie dans un nouveau flux de travail

Étapes suivantes