Программная настройка облачной синхронизации с использованием API MS Graph

В этом документе описано, как реплицировать профиль синхронизации с нуля с использованием только API MS Graph.
Структура реплика te профиля синхронизации состоит из следующих шагов. В их число входят:

• Программная настройка облачной синхронизации с использованием API MS Graph
  • Базовая настройка
    • Включение флагов клиента
  • Создание субъектов-служб
  • Создание задания синхронизации
  • Обновление целевого домена
  • Включение синхронизации хэшей паролей в колонке конфигурации
  • Гибридная обратная запись Exchange
  • Случайные удаления
    • Включение и установка порогового значения
    • Разрешение операций удаления
  • Запуск задания синхронизации
  • Просмотр состояния
  • Дальнейшие действия

Используйте эти команды Microsoft Graph PowerShell, чтобы включить синхронизацию для рабочего клиента, необходимое условие для вызова веб-службы Администратор istration для этого клиента.

Базовая настройка

Включение флагов клиента

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

Этот командлет включает синхронизацию для клиента. Он использует Get-MgOrganization для получения идентификатора организации.

Создание субъектов-служб

Далее необходимо создать приложение или субъект-службу AD2AAD.

Необходимо использовать идентификатор приложения 1a4721b3-e57f-4451-ae87-ef078703ec94. displayName — это URL-адрес домена AD, если он используется на портале (например, contoso.com), но он может называться по-другому.

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

Создание задания синхронизации

Выходные данные предыдущей команды возвращают объектный идентификатор созданного субъекта-службы. В этом примере objectId — aaaa-0000-1111-2222-bbbbbb. С помощью Microsoft Graph добавьте в этот субъект-службу задание синхронизации.

Документацию по созданию задания синхронизации можно найти здесь.

Если идентификатор не записан, можно найти субъект-службу, выполнив следующий вызов MS Graph. Для выполнения этого вызова требуются разрешения Directory.Read.All:

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

Затем найдите имя приложения в выходных данных.

Выполните следующие две команды, чтобы создать два задания: одно для подготовки пользователя или группы, а другое для синхронизации хэша паролей. Это один и тот же запрос с разными идентификаторами шаблонов.

Вызовите два следующих запроса.

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

Если вы хотите создать оба вызова, вам потребуется два вызова.

Пример возвращаемого значения (для подготовки)

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

Обновление целевого домена

Для этого клиента идентификатор объекта и идентификатор приложения субъекта-службы имеют следующие значения.

ObjectId: bbbbbbbb-1111-2222-3333-cccccccc AppId: 00001111-aaaa-2222-bbbb-333cc444 DisplayName: testApp

Нам необходимо обновить домен, для которого предназначена эта конфигурация, поэтому обновите секреты для этого домена.

Убедитесь, что используемое доменное имя совпадает с URL-адресом, заданным для локального контроллера домена.

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

Добавьте следующую пару "ключ — значение" в массив значений ниже, исходя из того, какую задачу вы хотите выполнить:

• включить флаги PHS и клиента синхронизации { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" };

• Включить только флаг клиента синхронизации (не включать PHS) { key: AppKey, value: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

Ожидаемый ответ HTTP 204. Содержимое отсутствует

Здесь выделенное значение "Домен" — это имя домена локальная служба Active Directory домена, из которого необходимо подготовить записи в идентификатор Microsoft Entra ID.

Включение синхронизации хэшей паролей в колонке конфигурации

В этом разделе описано, как включить синхронизацию хэшей паролей для определенной конфигурации. Эта ситуация отличается от секрета AppKey, который включает флаг компонента уровня клиента. Эта процедура предназначена только для одного домена или конфигурации. Для завершения этой процедуры необходимо установить ключ приложения на PHS.

1. Захватите схему (будьте внимательны, она достаточно большая):

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

2. Выполните это сопоставление атрибута CredentialData.

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

3. Найдите следующие сопоставления объектов со следующими именами в схеме.

   • Provision Active Directory Users
   • Provision Active Directory inetOrgPersons

   Сопоставления объектов находятся в схеме.synchronizationRules[0].objectMappings (Теперь можно предположить, что существует только одно правило синхронизации)

4. Возьмите сопоставление CredentialData из шага 2 и вставьте его в сопоставления объектов на шаге 3.

   Сопоставление объектов должно иметь следующий вид.

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

   Скопируйте и вставьте сопоставление из задания Create AD2AADProvisioning и AD2AADPasswordHash в массив attributeMappings.

   Порядок элементов в этом массиве не имеет значения (внутренние сортировки для вас). Будьте осторожны при добавлении этого сопоставления атрибутов, если имя уже существует в массиве (например, если в атрибутах уже есть элемент, имеющий targetAttributeName CredentialData), может возникнуть конфликтные ошибки или существующие и новые сопоставления могут объединяться вместе, обычно не нужный результат. Серверная часть не выделяет для вас.

   Не забудьте выполнить это действие как для пользователей, так и для пользователей и inetOrgpersons.

5. Сохраните созданную схему:

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

Добавьте схему в текст запроса.

Гибридная запись Exchange (общедоступная предварительная версия)

В этом разделе описывается, как включить и отключить и использовать гибридную запись Exchange программным способом.

Включение гибридной записи Exchange программным способом требует двух шагов.

1. Проверка схемы
2. Создание задания гибридной записи Exchange

Проверка схемы

Прежде чем включить и использовать гибридную запись Exchange, облачная синхронизация должна определить, была ли расширена локальная служба Active Directory, чтобы включить схему Exchange.

Для запуска обнаружения схем можно использовать directoryDefinition:discover .

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

Ожидаемый ответ HTTP 200/OK

Ответ должен выглядеть следующим образом:

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

Теперь проверка, чтобы узнать, присутствует ли атрибут mailNickName. Если это так, то схема проверяется и содержит атрибуты Exchange. В противном случае проверьте предварительные требования для гибридной записи Exchange.

Создание задания гибридной записи Exchange

После проверки схемы можно создать задание.

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

Случайные удаления

В этом разделе описывается, как программно включить или отключить и использовать случайные удаления программным способом.

Включение и установка порогового значения

Для каждого задания можно использовать два следующих параметра.

• DeleteThresholdEnabled: если этому параметру задано значение true, для задания включается защита от случайного удаления. Значение True задано по умолчанию.
• DeleteThresholdValue — определяет максимальное количество удалений, разрешенных в каждом выполнении задания при включении предотвращения случайного удаления. По умолчанию задано значение 500. Таким образом, если для значения задано значение 500, максимально допустимое число удалений равно 499 в каждом выполнении.

Параметры порога удаления являются частью SyncNotificationSettings и могут быть изменены с помощью Graph.

Нам необходимо обновить SyncNotificationSettings, для которого предназначена эта конфигурация, поэтому обновите секреты.

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

Добавьте следующую пару "ключ — значение" в массив значений ниже, исходя из того, какую задачу вы хотите выполнить:

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

Параметр "Включено" в примере предназначен для включения и отключения уведомлений по электронной почте при карантине задания.

В настоящее время мы не поддерживаем запросы PATCH для секретов, поэтому необходимо добавить все значения в текст запроса PUT (например, в примере), чтобы сохранить другие значения.

Существующие значения для всех секретов можно получить с помощью следующего запроса:

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

Разрешение операций удаления

Чтобы эти удаления проходили после того, как задание перейдет в карантин, необходимо выполнить перезапуск только с "ForceDeletes" в качестве область.

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

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

Запуск задания синхронизации

Задания можно получить еще раз с помощью следующей команды:

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

Документацию по получению заданий можно найти здесь.

Чтобы запустить задания, выполните этот запрос, используя objectId субъекта-службы, созданного на первом шаге, и идентификаторы заданий, возвращенные из запроса, создавшего задание.

Документацию по запуску задания можно найти здесь.

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

Ожидаемый ответ HTTP 204. Содержимое отсутствует.

Другие команды для управления заданием описаны здесь.

Чтобы перезапустить задание, используйте следующую команду:

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

Просмотр состояния

Получите сведения о состояниях заданий с помощью следующего запроса:

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

Просмотрите раздел status возвращаемого объекта, где приводятся соответствующие сведения.

Следующие шаги

• Что такое облачная синхронизация Microsoft Entra?
• Преобразования
• API синхронизации