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łączanie flag dzierżawy
  • Tworzenie jednostek usługi
  • Tworzenie zadania synchronizacji
  • Aktualizowanie domeny docelowej
  • Włączanie skrótów haseł synchronizacji w bloku konfiguracji
  • Zapisywanie zwrotne hybrydowe programu Exchange
  • Przypadkowe usunięcie
    • Włączanie i ustawianie progu
    • Zezwalanie na usuwanie
  • Uruchamianie zadania synchronizacji
  • Przeglądanie stanu
  • Następne kroki

Użyj tych poleceń programu PowerShell programu Microsoft Graph, aby włączyć synchronizację dla dzierżawy produkcyjnej, a wstępnie wymagane jest wywoływanie usługi sieci Web Administracja dla tej dzierżawy.

Konfiguracja podstawowa

Włączanie flag 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ę dzierżawy. Używa ona metody Get-MgOrganization , aby uzyskać identyfikator organizacji.

Tworzenie jednostek usługi

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 usługi 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 aaaaa-0000-1111-2222-bbbbbbbbbbbb. Użyj programu Microsoft Graph, aby dodać obiekt synchronizationJob do tej jednostki usługi.

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

Jeśli identyfikator nie został zarejestrowany, możesz znaleźć jednostkę usługi, uruchamiając następujące wywołanie programu MS Graph. Aby 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 aprowizacji użytkowników/grup i jedno na potrzeby synchronizacji skrótów haseł. To samo żądanie 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 jednostki 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ę docelową tej konfiguracji, więc zaktualizuj wpisy tajne 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 poniższą parę klucz/wartość do poniższej tablicy wartości na podstawie tego, co próbujesz zrobić.

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

• Włącz tylko flagę dzierżawy synchronizacji (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 domeny lokalna usługa Active Directory, z której wpisy mają być aprowidowane do identyfikatora Entra firmy Microsoft.

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 klucza tajnego AppKey, który umożliwia flagę funkcji na poziomie dzierżawy. Ta procedura dotyczy tylko jednej domeny/konfiguracji. Należy ustawić klucz aplikacji na phS jeden, aby ta procedura zakończyła pracę.

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. Wykonaj 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 (sortowanie zaplecza dla 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. Zaplecze 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 zapisywania zwrotnego programu Exchange wymaga dwóch kroków.

1. Weryfikacja schematu
2. Tworzenie zadania zapisywania zwrotnego hybrydowego programu Exchange

Weryfikacja schematu

Przed włączeniem i użycia funkcji hybrydowego zapisu zwrotnego Exchange synchronizacja w chmurze musi określić, czy lokalna usługa Active Directory została rozszerzona o schemat Exchange.

Aby zainicjować odnajdywanie schematów , możesz użyć kataloguDefinition: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 zapisywania zwrotnego hybrydowego programu 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ęcie

W tej sekcji opisano sposób programowego włączania/wyłączania i programowego używania przypadkowych operacji usuwania .

Włączanie i ustawianie progu

Istnieją dwa ustawienia zadania, których można użyć:

• 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 elementu i można je modyfikować za pomocą grafu.

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

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 wpisów tajnych 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 usuwania po przejściu zadania do kwarantanny, należy wydać ponowne uruchomienie za pomocą polecenia "ForceDeletes" jako zakresu.

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, wydaj to żądanie, używając identyfikatora objectId jednostki usługi utworzonej w pierwszym kroku, a identyfikatory zadań zwrócone z żądania, które utworzyły zadanie.

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

Przeglądanie stanu

Pobieranie stanów 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
• Interfejs API synchronizacji