Cloudsynchronisatie programmatisch configureren met behulp van MS Graph API

In het volgende document wordt beschreven hoe u een volledig nieuw synchronisatieprofiel repliceert met behulp van alleen MSGraph-API's.
De structuur van het repliceren van een synchronisatieprofiel bestaat uit de volgende stappen. Dit zijn:

• Cloudsynchronisatie programmatisch configureren met behulp van MS Graph API
  • Basisinstallatie
    • Tenantvlagmen inschakelen
  • Service-principals maken
  • Synchronisatietaak maken
  • Doeldomein bijwerken
  • Wachtwoordhashes synchroniseren inschakelen op de configuratieblade
  • Hybride Exchange-write-back
  • Onbedoelde verwijderingen
    • De drempelwaarde inschakelen en instellen
    • Verwijderingen toestaan
  • Synchronisatietaak starten
  • Status controleren
  • Volgende stappen 

Gebruik deze Microsoft Graph PowerShell-opdrachten om synchronisatie in te schakelen voor een productietenant, een vereiste voor het aanroepen van de Beheer istration-webservice voor die tenant.

Basisinstallatie

Tenantvlagmen inschakelen

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

Met deze cmdlet kunt u synchronisatie voor een tenant inschakelen. Het maakt gebruik van Get-MgOrganization om de id van de organisatie op te halen.

Service-principals maken

Vervolgens moeten we de AD2AAD-toepassing/service-principal maken

U moet deze toepassings-id 1a4721b3-e57f-4451-ae87-ef078703ec94 gebruiken. De displayName is de URL van het AD-domein, als deze wordt gebruikt in de portal (bijvoorbeeld contoso.com), maar deze kan een andere naam hebben.

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

Synchronisatietaak maken

De uitvoer van de voorgaande opdracht retourneert de object-id van de service-principal die is gemaakt. In dit voorbeeld is de objectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbbb. Gebruik Microsoft Graph om een synchronizationJob toe te voegen aan die service-principal.

Documentatie voor het maken van een synchronisatietaak vindt u hier.

Als u de id niet hebt opgenomen, kunt u de service-principal vinden door de volgende MS Graph-aanroep uit te voeren. U hebt Directory.Read.All-machtigingen nodig om die aanroep uit te voeren:

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

Zoek vervolgens in de uitvoer naar de naam van uw app.

Voer de volgende twee opdrachten uit om twee taken te maken: één voor het inrichten van gebruikers/groepen en één voor wachtwoord-hashsynchronisatie. Het is dezelfde aanvraag twee keer, maar met verschillende sjabloon-id's.

Roep de volgende twee aanvragen aan:

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

U hebt twee aanroepen nodig als u beide wilt maken.

Voorbeeld van retourwaarde (voor inrichting):

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": []
    }
}

Doeldomein bijwerken

Voor deze tenant zijn de object-id en toepassings-id van de service-principal als volgt:

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

We moeten het domein bijwerken dat deze configuratie is gericht, dus werk de geheimen voor dit domein bij.

Zorg ervoor dat de domeinnaam die u gebruikt dezelfde URL is die u hebt ingesteld voor uw on-premises domeincontroller.

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

Voeg het volgende sleutel-waardepaar toe in de onderstaande waardematrix op basis van wat u wilt doen:

• Schakel zowel PHS- als synchronisatietenantvlaggen { key: "AppKey", waarde: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Schakel alleen de vlag van de synchronisatietenant in (schakel PHS niet in) { sleutel: "AppKey", waarde: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Het verwachte antwoord is ... HTTP 204/Geen inhoud

Hier is de gemarkeerde waarde 'Domein' de naam van het on-premises Active Directory-domein waaruit vermeldingen moeten worden ingericht voor Microsoft Entra-id.

Wachtwoordhashes synchroniseren inschakelen op de configuratieblade

Deze sectie bevat informatie over het inschakelen van wachtwoordhashes voor een bepaalde configuratie. Deze situatie verschilt van het AppKey-geheim waarmee de functievlag op tenantniveau wordt ingeschakeld. Deze procedure is slechts voor één domein/configuratie. U moet de toepassingssleutel instellen op de PHS-sleutel voor deze procedure om end-to-end te werken.

1. Pak het schema (waarschuwing, het is vrij groot):

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

2. Voer de volgende toewijzing van het CredentialData-kenmerk uit:

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

3. Zoek de volgende objecttoewijzingen met de volgende namen in het schema

   • Active Directory-gebruikers inrichten
   • Active Directory inrichten inetOrgPersons

   Objecttoewijzingen bevinden zich in het schema.synchronizationRules[0].objectMappings (voorlopig kunt u aannemen dat er slechts één synchronisatieregel is)

4. Neem de CredentialData-toewijzing uit stap (2) en voeg deze in de objecttoewijzingen in stap (3) in

   Uw objecttoewijzing ziet er ongeveer als volgt uit:

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

   Kopieer/plak de toewijzing uit de taken Create AD2AADProvisioning en AD2AADPasswordHash in de matrix attributeMappings.

   Volgorde van elementen in deze matrix maakt niet uit (de back-end sorteert voor u). Wees voorzichtig met het toevoegen van deze kenmerktoewijzing als de naam al aanwezig is in de matrix (bijvoorbeeld als er al een item in attributeMappings is met de targetAttributeName CredentialData) - er kunnen conflictfouten optreden, of de bestaande en nieuwe toewijzingen kunnen samen worden gecombineerd, meestal niet het gewenste resultaat. Back-end ontdubbelt niet voor u.

   Vergeet niet om deze actie uit te voeren voor zowel gebruikers als inetOrgpersons.

5. Sla het schema op dat u maakt:

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

Voeg het schema toe in de aanvraagbody.

Hybride terugschrijven van Exchange (openbare preview)

In deze sectie wordt beschreven hoe u Exchange Hybrid WriteBack programmatisch inschakelt/uitschakelt en gebruikt.

Voor het programmatisch inschakelen van hybride write-back van Exchange zijn twee stappen vereist.

1. Schemaverificatie
2. De hybride write-backtaak voor Exchange maken

Schemaverificatie

Voordat u hybride write-back van Exchange inschakelt en gebruikt, moet cloudsynchronisatie bepalen of de on-premises Active Directory is uitgebreid om het Exchange-schema op te nemen.

U kunt directoryDefinition :discover gebruiken om schemadetectie te initiëren.

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

Het verwachte antwoord is ... HTTP 200/OK

Het antwoord moet er ongeveer uitzien als in de volgende uitvoer:

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

Controleer nu of het kenmerk mailNickName aanwezig is. Als dat het is, wordt uw schema geverifieerd en bevat u de Exchange-kenmerken. Als dat niet het is, controleert u de vereisten voor hybride terugschrijven van Exchange.

De hybride write-backtaak voor Exchange maken

Zodra u het schema hebt geverifieerd, kunt u de taak maken.

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

Onbedoelde verwijderingen

In deze sectie wordt beschreven hoe u programmatisch verwijderingen via een programma inschakelt/uitschakelt en gebruikt.

De drempelwaarde inschakelen en instellen

Er zijn twee per taakinstellingen die u kunt gebruiken:

• DeleteThresholdEnabled : hiermee schakelt u onbedoelde verwijderingspreventie voor de taak in wanneer deze is ingesteld op 'true'. Standaard ingesteld op 'true'.
• DeleteThresholdValue - Definieert het maximum aantal verwijderingen dat is toegestaan bij elke uitvoering van de taak wanneer onbedoeld verwijderen preventie is ingeschakeld. De waarde is standaard ingesteld op 500. Als de waarde dus is ingesteld op 500, is het maximum aantal toegestane verwijderingen 499 bij elke uitvoering.

De drempelwaarde-instellingen voor verwijderen maken deel uit van de SyncNotificationSettings instellingen en kunnen worden gewijzigd via grafiek.

We moeten de SyncNotification bijwerken Instellingen deze configuratie is gericht, dus werk de geheimen bij.

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

Voeg het volgende sleutel/waardepaar toe in de onderstaande waardematrix op basis van wat u probeert te doen:

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

De instelling Ingeschakeld in het voorbeeld is bedoeld voor het in- of uitschakelen van e-mailberichten voor meldingen wanneer de taak in quarantaine wordt geplaatst.

Momenteel bieden we geen ondersteuning voor PATCH-aanvragen voor geheimen. Daarom moet u alle waarden toevoegen in de hoofdtekst van de PUT-aanvraag (zoals in het voorbeeld) om de andere waarden te behouden.

De bestaande waarden voor alle geheimen kunnen worden opgehaald met behulp van:

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

Verwijderingen toestaan

Als u wilt toestaan dat deze verwijderingen doorstromen nadat de taak in quarantaine is geplaatst, moet u opnieuw opstarten met alleen ForceDeletes als bereik.

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

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

Synchronisatietaak starten

De taken kunnen opnieuw worden opgehaald via de volgende opdracht:

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

Documentatie voor het ophalen van taken vindt u hier.

Als u de taken wilt starten, geeft u deze aanvraag uit met behulp van de object-id van de service-principal die in de eerste stap is gemaakt en worden de taak-id's geretourneerd uit de aanvraag die de taak heeft gemaakt.

Hier vindt u documentatie voor het starten van een taak.

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

Het verwachte antwoord is ... HTTP 204/Geen inhoud.

Andere opdrachten voor het beheren van de taak worden hier beschreven.

Als u een taak opnieuw wilt starten, gebruikt u:

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

Status controleren

Haal uw taakstatussen op via:

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

Kijk onder de sectie Status van het retourobject voor relevante details

Volgende stappen

• Wat is Microsoft Entra-cloudsynchronisatie?
• Transformaties
• Synchronisatie-API