Comment configurer par programmation la synchronisation cloud avec l’API MS Graph

Le document suivant explique comment répliquer un profil de synchronisation à partir de zéro en utilisant uniquement des API MS Graph.
La réplication d’un profil de synchronisation se compose des étapes suivantes. Il s'agit des éléments suivants :

• Comment configurer par programmation la synchronisation cloud avec l’API MS Graph
  • Configuration de base
    • Activer les indicateurs de locataire
  • Créer des principaux de service
  • Créer une tâche de synchronisation
  • Mettre à jour un domaine ciblé
  • Activer les hachages de mot de passe de synchronisation dans le panneau de configuration
  • Écriture différée d’Exchange hybride
  • Suppressions accidentelles
    • Activation et définition du seuil
    • Autoriser les suppressions
  • Démarrer la tâche de synchronisation
  • Vérifier l’état
  • Étapes suivantes

Utilisez ces commandes Microsoft Graph PowerShell pour activer la synchronisation d’un locataire de production. Il s’agit d’un prérequis pour appeler le service web Administration de ce locataire.

Configuration de base

Activer les indicateurs de locataire

Connect-MgGraph -Scopes "DeviceManagementConfiguration.ReadWrite.All" ('-Environment <AzureEnvironment>')
$organizationId = (Get-MgOrganization).Id
$params = @{
	onPremisesSyncEnabled = $true
}
Update-MgBetaOrganization -OrganizationId $organizationId -BodyParameter $params

Cette applet de commande active la synchronisation pour un locataire. Il utilise le Get-MgOrganization pour obtenir l’ID de l’organisation.

Créer des principaux de service

Ensuite, nous devons créer l’application ou le principal de service AD2AAD.

Vous devez utiliser l’ID d’application 1a4721b3-e57f-4451-ae87-ef078703ec94. Le displayName correspond à l’URL du domaine Active Directory, si vous en utilisez une dans le portail (par exemple, contoso.com). Toutefois, elle peut porter un autre nom.

POST https://graph.microsoft.com/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate
Content-type: application/json
{
    displayName: [your app name here]
}

Créer une tâche de synchronisation

La sortie de la commande précédente retourne l’objectId du principal de service qui a été créé. Pour cet exemple, l’objectId est aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Utilisez Microsoft Graph pour ajouter un synchronizationJob à ce principal de service.

La documentation sur la création d’une tâche de synchronisation est disponible ici.

Si vous n’avez pas enregistré l’ID, vous pouvez trouver le principal de service en exécutant l’appel MS Graph suivant. Vous avez besoin des autorisations Directory.Read.All pour effectuer cet appel :

GET https://graph.microsoft.com/beta/servicePrincipals

Recherchez ensuite le nom de votre application dans la sortie.

Exécutez les deux commandes suivantes pour créer deux tâches : une pour le provisionnement d’utilisateurs ou de groupes, et une autre pour la synchronisation du hachage de mot de passe. Il s’agit de la même requête, mais avec des ID de modèle différents.

Appelez les deux requêtes suivantes :

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADProvisioning"
} 

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADPasswordHash"
}

Vous avez besoin de deux appels si vous souhaitez créer les deux requêtes.

Exemple de valeur renvoyée (pour le provisionnement) :

HTTP 201/Created
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbc')/synchronization/jobs/$entity",
    "id": "AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da",
    "templateId": "ADDCInPassthrough",
    "schedule": {
        "expiration": null,
        "interval": "PT40M",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "quarantine": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "troubleshootingUrl": null,
        "progress": [],
        "synchronizedEntryCountByType": []
    }
}

Mettre à jour un domaine ciblé

Pour ce locataire, l’identificateur d’objet et l’identificateur d’application du principal de service sont les suivants :

ObjectId: bbbbbbbb-1111-2222-3333-cccccccccccc
AppId: 00001111-aaaa-2222-bbbb-3333cccc4444
DisplayName: testApp

Vous allez devoir mettre à jour le domaine qui est ciblé par cette configuration. Pour cela, mettez à jour les secrets de ce domaine.

Vérifiez que le nom de domaine que vous utilisez correspond à l’URL que vous avez définie pour votre contrôleur de domaine local.

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

Ajoutez la paire clé/valeur suivante dans le tableau de valeurs ci-dessous en fonction de ce que vous essayez de faire :

• Activez les indicateurs de locataire PHS et de synchronisation { clé : "AppKey", valeur : "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Activez uniquement l’indicateur de locataire de synchronisation (n’activez pas PHS) { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

Request body –
{
   "value": [
              {
                "key": "Domain",
                "value": "{\"domain\":\"ad2aadTest.com\"}"
              }
            ]
}

La réponse attendue est... HTTP/204 No Content

Ici, la valeur « Domain » correspond au nom du domaine Active Directory local à partir duquel les entrées doivent être provisionnées pour Microsoft Entra ID.

Activer les hachages de mot de passe de synchronisation dans le panneau de configuration

Cette section aborde l’activation des hachages de mot de passe de synchronisation pour une configuration particulière. Cette situation diffère de la clé secrète AppKey qui active l’indicateur de fonctionnalité au niveau locataire. Cette procédure ne concerne qu’un seul domaine/configuration. Vous devez définir la clé d’application sur le PHS un pour que cette procédure fonctionne de bout en bout.

1. Récupérez le schéma (attention, il est assez grand) :

   GET –https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

2. Prenez ce mappage d’attribut CredentialData :

   {
   "defaultValue": null,
   "exportMissingReferences": false,
   "flowBehavior": "FlowWhenChanged",
   "flowType": "Always",
   "matchingPriority": 0,
   "targetAttributeName": "CredentialData",
   "source": {
   "expression": "[PasswordHash]",
   "name": "PasswordHash",
   "type": "Attribute",
   "parameters": []
   }
   

3. Recherchez les mappages d’objets suivants avec les noms suivants dans le schéma

   • Approvisionnez des utilisateurs Active Directory
   • Approvisionnez des inetOrgPersons Active Directory

   Les mappages d’objets se trouvent dans schema.synchronizationRules[0].objectMappings (pour le moment, vous pouvez supposer qu’il n’y a qu’une seule règle de synchronisation)

4. Effectuez le mappage CredentialData de l’étape (2) et insérez-le dans les mappages d’objets à l’étape (3)

   Votre mappage d’objet ressemble à ceci :

   {
   "enabled": true,
   "flowTypes": "Add,Update,Delete",
   "name": "Provision Active Directory users",
   "sourceObjectName": "user",
   "targetObjectName": "User",
   "attributeMappings": [
   ...
   } 
   

   Copiez/collez le mappage de l’étape Créer des travaux AD2AADProvisioning et AD2AADPasswordHash dans le tableau attributeMappings.

   L’ordre des éléments dans ce tableau n’a pas d’importance (le serveur principal effectuera le tri pour vous). Veillez à ajouter ce mappage d’attribut si le nom existe déjà dans le tableau (par exemple, s’il existe déjà un élément dans attributeMappings qui a le targetAttributeName CredentialData). Il se peut que vous rencontriez des erreurs de conflit, ou que les mappages préexistants et nouveaux soient combinés (ce qui n’est généralement pas le résultat souhaité). Le serveur principal ne déduplique pas pour vous.

   N’oubliez pas d’effectuer cette action pour les utilisateurs et les inetOrgpersons.

5. Enregistrez le schéma que vous créez :

   PUT –
   https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

Ajoutez le schéma dans le corps de la demande.

Écriture différée hybride Exchange (préversion publique)

Cette section explique comment activer/désactiver et utiliser l’écriture différée hybride Exchange par programmation.

Son activation se fait en deux étapes.

1. Vérification du schéma
2. Créer la tâche d’écriture différée hybride Exchange

Vérification du schéma

Avant que vous activiez et utilisiez l’écriture différée hybride Exchange, la synchronisation cloud doit déterminer si le service Active Directory local a été étendu afin d’inclure le schéma Exchange.

Vous pouvez utiliser directoryDefinition:discover pour lancer une découverte de schéma.

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/[AD2AADProvisioningJobId]/schema/directories/[ADDirectoryID]/discover

La réponse attendue est... HTTP 200/OK

La réponse doit être semblable à la sortie suivante :

HTTP/1.1 200 OK
Content-type: application/json
{
  "objects": [
    {
      "name": "user",
      "attributes": [
        {
          "name": "mailNickName",
          "type": "String"
        },
        ...
      ]
    },
    ...
  ]
}

Vérifiez ensuite si l’attribut mailNickName est présent. Si tel est le cas, votre schéma est vérifié et contient les attributs Exchange. Dans le cas contraire, examinez les prérequis pour l’écriture différée hybride Exchange.

Créer la tâche d’écriture différée hybride Exchange

Une fois le schéma vérifié, vous pouvez créer la tâche.

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AAD2ADExchangeHybridWriteback"
}

Suppressions accidentelles

Cette section explique comment activer/désactiver et utiliser des suppressions accidentelles par programmation.

Activation et définition du seuil

Il existe deux paramètres par travail que vous pouvez utiliser, à savoir :

• DeleteThresholdEnabled : active la prévention de suppression accidentelle pour le travail quand la valeur est « true ». Valeur « true » par défaut.
• DeleteThresholdValue : définit le nombre maximal de suppressions qui seront autorisées dans chaque exécution du travail lorsque la prévention des suppressions accidentelles est activée. La valeur définie par défaut est 500. Ainsi, si la valeur est définie sur 500, le nombre maximal de suppressions autorisées sera de 499 dans chaque exécution.

Les paramètres de seuil de suppression font partie des paramètres SyncNotificationSettings et peuvent être modifiés via un graphique.

Nous allons devoir mettre à jour les paramètres SyncNotificationSettings que cette configuration cible, et donc mettre à jour les secrets.

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

Ajoutez la paire clé/valeur suivante dans le tableau de valeurs ci-dessous en fonction de ce que vous essayez de faire :

Request body -
{
  "value":[
    {
      "key":"SyncNotificationSettings",
      "value": "{\"Enabled\":true,\"Recipients\":\"foobar@xyz.com\",\"DeleteThresholdEnabled\":true,\"DeleteThresholdValue\":50}"
     }
  ]
}

Le paramètre « Activé » dans l’exemple permet d’activer ou de désactiver les e-mails de notification lorsque le travail est mis en quarantaine.

Les requêtes PATCH pour les secrets n’étant actuellement pas prises en charge, vous devez ajouter toutes les valeurs dans le corps de la requête PUT (comme dans l’exemple) afin de conserver les autres valeurs.

Vous pouvez récupérer les valeurs existantes pour tous les secrets à l’aide de :

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

Autoriser les suppressions

Pour autoriser le passage des suppressions une fois le travail en quarantaine, vous devez lancer un redémarrage avec simplement « ForceDeletes » comme étendue.

Request:
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

Request Body:
{
  "criteria": {"resetScope": "ForceDeletes"}
}

Démarrer la tâche de synchronisation

Les tâches peuvent être récupérées à nouveau à l’aide de la commande suivante :

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

La documentation concernant la récupération des tâches est disponible ici.

Pour démarrer les tâches, émettez cette requête à l’aide de l’objectId du principal de service créé à la première étape, et des identificateurs de tâche renvoyés par la requête qui a créé la tâche.

La documentation expliquant comment démarrer une tâche est disponible ici.

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

La réponse attendue est... HTTP/204 No Content.

Les autres commandes permettant de contrôler les tâches sont documentées ici.

Pour redémarrer un travail :

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/restart
{
  "criteria": {
    "resetScope": "Full"
  }
}

Vérifier l’état

Récupérez l’état de vos tâches via :

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ 

Pour plus de détails, regardez sous la section « status » de l’objet retourné.

Étapes suivantes

• Qu’est-ce que Microsoft Entra Cloud Sync ?
• Transformations
• API de synchronisation