Programmgesteuertes Konfigurieren der Cloudsynchronisierung mithilfe der Microsoft Graph-API

Im folgenden Dokument wird beschrieben, wie Sie ein Synchronisierungsprofil mithilfe von MS Graph-APIs von Grund auf neu replizieren.
Die Struktur für die Replikation eines Synchronisierungsprofils besteht aus den folgenden Schritten. Sie lauten wie folgt:

• Programmgesteuertes Konfigurieren der Cloudsynchronisierung mithilfe der Microsoft Graph-API
  • Grundlegende Einrichtung
    • Aktivieren von Mandantenflags
  • Erstellen von Dienstprinzipalen
  • Erstellen des Synchronisierungsauftrags
  • Aktualisieren der Zieldomäne
  • Aktivieren der Synchronisierung von Kennworthashes auf dem Blatt „Konfiguration“
  • Exchange-Hybridrückschreiben
  • Versehentliche Löschvorgänge
    • Aktivieren und Festlegen des Schwellenwerts
    • Löschvorgänge werden zugelassen
  • Starten des Synchronisierungsauftrags
  • Überprüfen des Status
  • Nächste Schritte

Verwenden Sie diese Microsoft Graph PowerShell-Befehle, um die Synchronisierung für einen Produktionsmandanten zu aktivieren. Dies ist eine Voraussetzung dafür, dass der Verwaltungswebdienst für diesen Mandanten aufgerufen werden kann.

Grundlegende Einrichtung

Aktivieren von Mandantenflags

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

Dieses Cmdlet ermöglicht die Synchronisierung für einen Mandanten. Es verwendet die Get-MgOrganization, um die ID der Organisation abzurufen.

Erstellen von Dienstprinzipalen

Als Nächstes müssen Sie die AD2AAD-Anwendung mit Dienstprinzipal erstellen.

Sie müssen diese Anwendungs-ID verwenden: 1a4721b3-e57f-4451-ae87-ef078703ec94. Der Anzeigename (displayName) ist bei Verwendung im Portal die URL der AD-Domäne (z. B. contoso.com), er kann aber umbenannt werden.

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

Erstellen des Synchronisierungsauftrags

In der Ausgabe des obigen Befehls wird die Objekt-ID (objectId) des erstellten Dienstprinzipals zurückgegeben. In diesem Beispiel lautet die objectId 614ac0e9-a59b-481f-bd8f-79a73d167e1c. Fügen Sie dem Dienstprinzipal mit Microsoft Graph einen Synchronisierungsauftrag hinzu.

Eine Dokumentation zum Erstellen eines Synchronisierungsauftrags finden Sie hier.

Falls Sie sich die ID nicht notiert haben, können Sie den Dienstprinzipal mit dem folgenden MS Graph-Aufruf ermitteln. Sie benötigen für diesen Aufruf die Berechtigung „Directory.Read.All“:

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

Suchen Sie dann in der Ausgabe nach dem Namen Ihrer App.

Führen Sie die folgenden beiden Befehle aus, um zwei Aufträge zu erstellen: einen für die Benutzer-/Gruppenbereitstellung und einen für die Kennworthashsynchronisierung. Dabei handelt es sich zweimal um dieselbe Anforderung, aber mit unterschiedlichen Vorlagen-IDs.

Rufen Sie die beiden folgenden Anforderungen auf:

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

Wenn Sie beides erstellen möchten, benötigen Sie zwei Aufrufe.

Beispielrückgabewert (für die Bereitstellung):

HTTP 201/Created
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('614ac0e9-a59b-481f-bd8f-79a73d167e1c')/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": []
    }
}

Aktualisieren der Zieldomäne

Für diesen Mandanten lauten der Objektbezeichner und der Anwendungsbezeichner des Dienstprinzipals wie folgt:

Objekt-ID: 8895955e-2e6c-4d79-8943-4d72ca36878f App-ID: 00000014-0000-0000-c000-000000000000, Anzeigename: testApp

Sie müssen die Domäne aktualisieren, auf die diese Konfiguration abzielt, indem Sie die Geheimnisse für diese Domäne aktualisieren.

Stellen Sie sicher, dass der von Ihnen verwendete Domänenname dieselbe URL ist, die Sie für Ihren lokalen Domänencontroller festgelegt haben.

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

Fügen Sie das folgende Schlüssel-Wert-Paar in das unten angegebene Wertarray ein, je nachdem, was Sie ausführen möchten:

• Aktivieren von PHS-Flag und Flag des Synchronisierungsmandanten: { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Nur das Flag des Synchronisierungsmandanten aktivieren (nicht PHS) { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Die erwartete Antwort lautet: HTTP 204/No Content.

Dabei ist der hervorgehobene Wert „Domain“ der Name der lokalen Active Directory-Domäne, von der Einträge in Microsoft Entra ID bereitgestellt werden sollen.

Aktivieren der Synchronisierung von Kennworthashes auf dem Blatt „Konfiguration“

In diesem Abschnitt wird das Aktivieren der Synchronisierung von Kennworthashes für eine bestimmte Konfiguration behandelt. Diese Situation unterscheidet sich vom AppKey-Geheimnis für die Aktivierung des Featureflags auf Mandantenebene. Dieses Verfahren gilt nur für eine einzelne Domäne/Konfiguration. Sie müssen den Anwendungsschlüssel auf das PHS-Flag festlegen, damit dieses Verfahren vollständig funktioniert.

1. Rufen Sie das Schema ab (Warnung: sehr groß):

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

2. Verwenden Sie diese Attributzuordnung von CredentialData:

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

3. Suchen Sie die Objektzuordnungen mit den folgenden Namen im Schema:

   • Provision Active Directory Users
   • Provision Active Directory inetOrgPersons

   Sie finden die Objektzuordnungen in „schema.synchronizationRules[0].objectMappings“. (Sie können hier davon ausgehen, dass es nur eine Synchronisierungsregel gibt.)

4. Fügen Sie die CredentialData-Zuordnung aus Schritt 2 in die Objektzuordnungen in Schritt 3 ein.

   Ihre Objektzuordnung sollte der folgenden ähneln:

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

   Kopieren Sie die Zuordnung aus dem Schritt zum Erstellen der Aufträge AD2AADProvisioning und AD2AADPasswordHash in das attributeMappings-Array.

   Die Reihenfolge der Elemente in diesem Array spielt keine Rolle, da sie vom Back-End sortiert werden. Gehen Sie beim Hinzufügen dieser Attributzuordnung vorsichtig vor: Wenn der Name bereits im Array vorhanden ist (z. B. da es in attributeMappings bereits ein Element mit dem targetAttributeName-Wert „CredentialData“ gibt), treten möglicherweise Konflikte auf, oder die vorhandene und die neue Zuordnung werden miteinander kombiniert (das Ergebnis ist normalerweise nicht wünschenswert). Duplikate werden vom Back-End nicht für Sie gelöscht.

   Führen Sie diese Aktion sowohl für „Users“ als auch für „inetOrgpersons“ aus.

5. Speichern Sie das von Ihnen erstellte Schema:

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

Fügen Sie das Schema in den Anforderungstext ein.

Exchange-Hybridrückschreiben (Public Preview)

In diesem Abschnitt wird behandelt, wie Sie Exchange-Hybridrückschreiben programmgesteuert aktivieren/deaktivieren und verwenden.

Zum programmgesteuerten Aktivieren des Exchange-Hybridrückschreibens sind zwei Schritte erforderlich.

1. Schemaüberprüfung
2. Erstellen des Exchange-Hybridrückschreibauftrags

Schemaüberprüfung

Vor dem Aktivieren und Verwenden des Exchange-Hybridrückschreibens muss die Cloudsynchronisierung bestimmen, ob das lokale Active Directory um das Exchange-Schema erweitert wurde oder nicht.

Sie können mit directoryDefinition:discover die Schemaermittlung initiieren.

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

Die erwartete Antwort lautet: HTTP 200/OK

Die Antwort sollte in etwa wie die folgende Ausgabe aussehen:

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

Überprüfen Sie nun, ob das Attribut mailNickName vorhanden ist. Wenn es vorhanden ist, wird Ihr Schema überprüft und enthält die Exchange-Attribute. Andernfalls überprüfen Sie die Voraussetzungen für das Exchange-Hybridrückschreiben.

Erstellen des Exchange-Hybridrückschreibauftrags

Nachdem Sie das Schema überprüft haben, können Sie den Auftrag erstellen.

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

Versehentliche Löschvorgänge

In diesem Abschnitt wird erläutert, wie Sie versehentliche Löschvorgänge programmgesteuert aktivieren, deaktivieren und verwenden.

Aktivieren und Festlegen des Schwellenwerts

Es gibt zwei Einstellungen pro Auftrag, die Sie verwenden können:

• DeleteThresholdEnabled: Ermöglicht das Verhindern versehentlicher Löschvorgänge für den Auftrag, wenn diese Einstellung auf „true“ festgelegt wurde. Die Standardeinstellung lautet „true“.
• „DeleteThresholdValue“ definiert die maximale Anzahl von Löschvorgängen, die bei einer Ausführung des Auftrags zulässig sind, wenn die Einstellung zum Verhindern versehentlicher Löschvorgänge aktiviert ist. Standardmäßig ist der Wert auf „500“ festgelegt. Wenn der Wert also auf „500“ festgelegt ist, beträgt die maximale Anzahl von Löschvorgängen pro Ausführung 499.

Die Schwellenwerteinstellungen für Löschvorgänge sind Teil der SyncNotificationSettings und können über Graph geändert werden.

Sie müssen die SyncNotificationSettings aktualisieren, auf die diese Konfiguration abzielt. Aktualisieren Sie daher die Geheimnisse.

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

Fügen Sie das folgende Schlüssel-Wert-Paar in das unten angegebene Wertarray ein, je nachdem, was Sie ausführen möchten:

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

Die Einstellung „Enabled“ im Beispiel dient zum Aktivieren bzw. Deaktivieren von Benachrichtigungs-E-Mails, wenn der Auftrag unter Quarantäne gestellt wird.

Zurzeit werden keine PATCH-Anforderungen für Geheimnisse unterstützt. Deshalb müssen Sie (wie im Beispiel) alle Werte im Text der PUT-Anforderung hinzufügen, um die anderen Werte beizubehalten.

Die vorhandenen Werte für alle Geheimnisse können wie folgt abgerufen werden:

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

Löschvorgänge werden zugelassen

Damit diese Löschvorgänge durchlaufen werden können, nachdem der Auftrag unter Quarantäne gestellt wurde, müssen Sie einen Neustart nur mit „ForceDeletes“ als Bereich ausgeben.

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

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

Starten des Synchronisierungsauftrags

Die Aufträge können mit dem folgenden Befehl erneut abgerufen werden:

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

Die Dokumentation zum Abrufen von Aufträgen finden Sie hier.

Um die Aufträge zu starten, geben Sie diese Anforderung mithilfe der Objekt-ID des im ersten Schritt erstellten Dienstprinzipals und der von der Anforderung für die Auftragserstellung zurückgegebenen Auftragsbezeichner an.

Die Dokumentation zum Starten eines Auftrags finden Sie hier.

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

Die erwartete Antwort lautet: HTTP 204/No Content.

Weitere Befehle zum Steuern von Aufträgen sind hier dokumentiert.

Vorgehensweise beim Neustart eines Auftrags:

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

Überprüfen des Status

Rufen Sie den Auftragsstatus ab:

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

Suchen Sie im Abschnitt „status“ des Rückgabeobjekts nach relevanten Details.

Nächste Schritte

• Was ist Microsoft Entra Cloud Sync?
• Transformationen
• Synchronisierungs-API