Jak programowo skonfigurować synchronizację w chmurze przy użyciu interfejsu API programu MS Graph

W poniższym dokumencie opisano sposób replikowania profilu synchronizacji od podstaw przy użyciu tylko interfejsów API MSGraph.
Struktura replikacji profilu synchronizacji składa się z poniższych kroków. Są to:

• Jak programowo skonfigurować synchronizację w chmurze przy użyciu interfejsu API programu MS Graph
  • Konfiguracja podstawowa
    • Włącz flagi dzierżawców
  • Tworzenie jednostek usługi
  • Tworzenie zadania synchronizacji
  • Aktualizowanie domeny docelowej
  • Włącz synchronizację skrótów haseł w panelu konfiguracji
  • Zapisywanie zwrotne hybrydowe programu Exchange
  • Przypadkowe usunięcie
    • Włączanie i ustawianie progu
    • Zezwalanie na usuwanie
  • Uruchamianie zadania synchronizacji
  • Status przeglądu
  • Następne kroki

Użyj tych poleceń Microsoft Graph PowerShell, aby włączyć synchronizację dla dzierżawy produkcyjnej, co jest warunkiem wstępnym do wywołania usługi sieciowej administracji dla tej dzierżawy.

Konfiguracja podstawowa

Włącz flagi dzierżawy

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

To polecenie cmdlet umożliwia synchronizację dla klienta. Używa ona metody Get-MgOrganization , aby uzyskać identyfikator organizacji.

Tworzenie tożsamości usługowych

Następnie musimy utworzyć aplikację AD2AAD/jednostkę usługi

Należy użyć tego identyfikatora aplikacji 1a4721b3-e57f-4451-ae87-ef078703ec94. DisplayName to adres URL domeny AD, jeśli jest używany w portalu (na przykład contoso.com), ale może mieć inną nazwę.

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

Tworzenie zadania synchronizacji

Dane wyjściowe poprzedniego polecenia zwracają identyfikator objectId utworzonej jednostki usługi. W tym przykładzie objectId to aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Użyj Microsoft Graph, aby dodać obiekt synchronizationJob do tego głównego obiektu usługi.

Dokumentację dotyczącą tworzenia zadania synchronizacji można znaleźć tutaj.

Jeśli nie zanotowałeś identyfikatora, możesz znaleźć główny obiekt usługi, uruchamiając następujące wywołanie programu MS Graph. Aby móc wykonać to wywołanie, potrzebujesz uprawnień Directory.Read.All.

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

Następnie poszukaj nazwy aplikacji w danych wyjściowych.

Uruchom następujące dwa polecenia, aby utworzyć dwa zadania: jedno dla udostępniania użytkowników/grup i jedno do synchronizacji skrótów haseł. To samo żądanie powtórzone dwa razy, ale z różnymi identyfikatorami szablonów.

Wywołaj następujące dwa żądania:

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

Jeśli chcesz utworzyć oba wywołania, potrzebne są dwa wywołania.

Przykładowa wartość zwracana (na potrzeby aprowizacji):

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

Aktualizowanie domeny docelowej

W przypadku tej dzierżawy identyfikator obiektu i identyfikator aplikacji głównego użytkownika usługi są następujące:

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

Będziemy musieli zaktualizować domenę, do której odnosi się ta konfiguracja, więc zaktualizuj sekrety dla tej domeny.

Upewnij się, że używana nazwa domeny jest tym samym adresem URL ustawionym dla lokalnego kontrolera domeny.

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

Dodaj następującą parę klucz/wartość do podanej tablicy wartości zależnie od tego, co próbujesz osiągnąć.

• Włącz zarówno phS, jak i synchronizuj flagi dzierżawy { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Włącz tylko flagę synchronizacji tenant (nie włączaj funkcji PHS) { key: "AppKey", wartość: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Oczekiwana odpowiedź to ... HTTP 204/Brak zawartości

W tym miejscu wyróżniona wartość "Domena" to nazwa lokalnej domeny Active Directory, z której wpisy mają być udostępniane do Microsoft Entra ID.

Włączanie skrótów haseł synchronizacji w bloku konfiguracji

W tej sekcji opisano włączanie synchronizowania skrótów haseł dla określonej konfiguracji. Ta sytuacja różni się od tajnego klucza AppKey, który umożliwia flagę funkcjonalności na poziomie dzierżawcy. Ta procedura dotyczy tylko jednej domeny/konfiguracji. Należy ustawić klucz aplikacji na ten z PHS, aby ta procedura działała od początku do końca.

1. Pobierz schemat (ostrzeżenie, jest dość duże):

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

2. Wykonaj to mapowanie atrybutów CredentialData:

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

3. Znajdź następujące mapowania obiektów o następujących nazwach w schemacie

   • Aprowizuj użytkowników usługi Active Directory
   • Aprowizuj usługę Active Directory inetOrgPersons

   Mapowania obiektów znajdują się w schema.synchronizationRules[0].objectMappings (na razie można założyć, że istnieje tylko jedna reguła synchronizacji)

4. Weź mapowanie CredentialData z Kroku (2) i wstaw je do mapowań obiektów w Kroku (3)

   Mapowanie obiektu wygląda następująco:

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

   Skopiuj/wklej mapowanie z kroku Tworzenie zadań AD2AADProvisioning i AD2AADPasswordHash do tablicy attributeMappings.

   Kolejność elementów w tej tablicy nie ma znaczenia (zaplecze sortuje za Ciebie). Należy zachować ostrożność podczas dodawania tego mapowania atrybutów, jeśli nazwa już istnieje w tablicy. Jeśli na przykład w attributeMappings istnieje już element, który ma targetAttributeName CredentialData, mogą wystąpić błędy konfliktu lub istniejące i nowe mapowania mogą być połączone. Zazwyczaj nie jest to pożądany wynik. Backend nie deduplikuje dla ciebie.

   Pamiętaj, aby wykonać tę akcję zarówno dla użytkowników, jak i inetOrgpersons.

5. Zapisz utworzony schemat:

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

Dodaj schemat w treści żądania.

Zapisywanie zwrotne hybrydowe programu Exchange (publiczna wersja zapoznawcza)

W tej sekcji opisano sposób włączania/wyłączania i programowego używania funkcji zapisywania zwrotnego hybrydowego programu Exchange.

Włączenie hybrydowego mechanizmu zapisu zwrotnego w Exchange wymaga dwóch kroków.

1. Weryfikacja schematu
2. Utwórz zadanie zapisywania zwrotnego hybrydowego dla programu Exchange

Weryfikacja schematu

Przed włączeniem i używaniu funkcjonalności hybrydowego zapisu zwrotnego w Exchange, synchronizacja w chmurze musi określić, czy lokalny Active Directory został rozszerzony o schemat Exchange.

Aby zainicjować odkrywanie schematów, możesz użyć directoryDefinition:discover.

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

Oczekiwana odpowiedź to ... HTTP 200/OK

Odpowiedź powinna wyglądać podobnie do następujących danych wyjściowych:

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

Teraz sprawdź, czy atrybut mailNickName jest obecny. Jeśli tak jest, schemat zostanie zweryfikowany i zawiera atrybuty programu Exchange. Jeśli nie, zapoznaj się z wymaganiami wstępnymi dotyczącymi hybrydowego zapisu zwrotnego w Exchange.

Tworzenie zadania zapisywania zwrotnego hybrydowego programu Exchange

Po zweryfikowaniu schematu można utworzyć zadanie.

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

Przypadkowe usunięcia

W tej sekcji opisano, jak programowo włączać/wyłączać oraz używać przypadkowego usuwania.

Włączanie i ustawianie progu

Istnieją dwa ustawienia na jedno zadanie, których można użyć, są to:

• DeleteThresholdEnabled — włącza przypadkowe zapobieganie usuwaniu zadania po ustawieniu wartości "true". Ustaw wartość "true" domyślnie.
• DeleteThresholdValue — definiuje maksymalną liczbę operacji usuwania dozwolonych w każdym wykonaniu zadania, gdy jest włączona funkcja zapobiegania przypadkowym usunięciom. Wartość jest domyślnie ustawiona na 500. Dlatego jeśli wartość jest ustawiona na 500, maksymalna dozwolona liczba operacji usuwania wynosi 499 w każdym wykonaniu.

Ustawienia progu usuwania są częścią SyncNotificationSettings i można je modyfikować przez wykres.

Będziemy musieli zaktualizować element SyncNotificationSettings, dla którego jest przeznaczona ta konfiguracja, więc zaktualizuj sekrety.

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

Dodaj następującą parę klucz/wartość do podanej tablicy wartości, w zależności od Twojego celu.

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

Ustawienie "Włączone" w przykładzie dotyczy włączania/wyłączania wiadomości e-mail z powiadomieniami, gdy zadanie jest poddane kwarantannie.

Obecnie żądania PATCH dotyczące sekretów nie są obsługiwane. Dlatego należy dodać wszystkie wartości w treści żądania PUT, tak jak w przykładzie, aby zachować inne wartości.

Istniejące wartości dla wszystkich tajemnic można pobrać przy użyciu:

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

Zezwalanie na usuwanie

Aby zezwolić na przepływ tych usunięć po przejściu zadania do kwarantanny, należy wydać ponowne uruchomienie z zakresem ustawionym na "ForceDeletes".

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

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

Uruchamianie zadania synchronizacji

Zadania można pobrać ponownie za pomocą następującego polecenia:

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

Dokumentację dotyczącą pobierania zadań można znaleźć tutaj.

Aby uruchomić zadania, wykonaj to żądanie, używając identyfikatora objectId jednostki usługi utworzonej w pierwszym kroku, oraz identyfikatorów zadań zwróconych przez żądanie, które utworzyło zadania.

Dokumentację dotyczącą uruchamiania zadania można znaleźć tutaj.

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

Oczekiwana odpowiedź to ... HTTP 204/Brak zawartości.

Inne polecenia do kontrolowania zadania są udokumentowane tutaj.

Aby ponownie uruchomić zadanie, użyj:

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

Status przeglądu

Pobierz stan zadań za pośrednictwem:

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

Zapoznaj się z sekcją "status" obiektu zwracanego, aby uzyskać odpowiednie szczegóły

Następne kroki

• Co to jest usługa Microsoft Entra Cloud Sync?
• Przekształcenia
• API synchronizacji