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

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

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

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

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

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

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 — aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. С помощью 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-cccccccccccc
AppId: 00001111-aaaa-2222-bbbb-3333cccc4444
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. Найдите следующие сопоставления объектов со следующими именами в схеме.

   • Настройка пользователей в Active Directory
   • Настройка 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.

   Порядок элементов в этом массиве не имеет значения (сервер автоматически сортирует их для вас). Будьте осторожны при добавлении этого сопоставления атрибутов, если имя уже существует в массиве. Например, если в 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 и могут быть изменены с помощью графика.

Нам необходимо обновить 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 синхронизации