Настройка подготовки с помощью API Microsoft Graph

Статья
04/06/2024

Центр администрирования Microsoft Entra — удобный способ настройки подготовки для отдельных приложений одновременно. Но если вы создаете несколько (или даже сотни) экземпляров приложения или переносите конфигурацию приложений из одной среды в другую, проще автоматизировать создание и настройку приложений с помощью API Microsoft Graph. В этой статье рассказывается о том, как автоматизировать подготовку конфигураций с помощью API. Этот метод обычно используется для таких приложений, как Amazon Web Services.

В этой статье показано, как использовать API в конечной точке бета-версии Microsoft Graph и Microsoft Graph Обозреватель; аналогичные API также доступны в конечной точке Microsoft Graph версии 1.0. Пример настройки подготовки с помощью Graph версии 1.0 и PowerShell см. в шагах 6-13 по настройке синхронизации между клиентами с помощью PowerShell или API Microsoft Graph.

Общие сведения о действиях по использованию Microsoft Graph API для автоматизации настройки подготовки

Этап	Сведения
Шаг 1. Создание приложения из коллекции	Вход в клиент API Получение шаблона приложения коллекции Создание приложения из коллекции
Шаг 2. Создание задания подготовки на основе шаблона	Получение шаблона для соединителя подготовки Создание задания подготовки
Шаг 3. Авторизация доступа	Проверка подключения к приложению Сохранение учетных данных
Шаг 4. Начало подготовки к работе	Запуск задания
Шаг 5. Мониторинг подготовки к работе	Проверка состояния задания подготовки Получение журналов подготовки

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

Шаг 1. Создание приложения коллекции

Запустите Microsoft Graph Explorer.
Нажмите кнопку "Вход с помощью Майкрософт" и войдите с помощью microsoft Entra Global Администратор istrator или учетных данных app Администратор.
После успешного входа вы увидите данные учетной записи пользователя на панели слева.

Получение идентификатора шаблона для приложения в коллекции

Приложения в коллекции приложений Microsoft Entra имеют шаблон приложения, описывающий метаданные для этого приложения. По этому шаблону вы можете создать экземпляр приложения и субъект-службу в клиенте для управления им. Извлеките идентификатор шаблона приложения для AWS Single-Account Access, найдите в ответе значение свойства ID и запишите его (оно будет использоваться далее в этом руководстве).

Запросить

GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
  {
    "id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Single-Account Access",
        "homePageUrl": "http://aws.amazon.com/",
        "supportedSingleSignOnModes": [
             "password",
             "saml",
             "external"
         ],
         "supportedProvisioningTypes": [
             "sync"
         ],
         "logoUrl": "https://az495088.vo.msecnd.net/app-logo/aws_215.png",
         "categories": [
             "developerServices"
         ],
         "publisher": "Amazon",
         "description": "Federate to a single AWS account and use SAML claims to authorize access to AWS IAM roles. If you have many AWS accounts, consider using the AWS Single Sign-On gallery application instead."    

}

Создание приложения из коллекции

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

Запросить

POST https://graph.microsoft.com/beta/applicationTemplates/{applicationTemplateId}/instantiate
Content-type: application/json

{
  "displayName": "AWS Contoso"
}

Response

HTTP/1.1 201 OK
Content-type: application/json

{
    "application": {
        "objectId": "cbc071a6-0fa5-4859-8g55-e983ef63df63",
        "appId": "92653dd4-aa3a-3323-80cf-e8cfefcc8d5d",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Contoso",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "logoutUrl": null,
        "samlMetadataUrl": null,
    },
    "servicePrincipal": {
        "objectId": "f47a6776-bca7-4f2e-bc6c-eec59d058e3e",
        "appDisplayName": "AWS Contoso",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "appRoleAssignmentRequired": true,
        "displayName": "My custom name",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "servicePrincipalNames": [
            "93653dd4-aa3a-4323-80cf-e8cfefcc8d7d"
        ],
        "tags": [
            "WindowsAzureActiveDirectoryIntegratedApp"
        ],
    }
}

Шаг 2. Создание задания подготовки на основе шаблона

Получение шаблона для соединителя подготовки

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

Запросить

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

Response

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "aws",
            "factoryTag": "aws",
            "schema": {
                    "directories": [],
                    "synchronizationRules": []
                    }
        }
    ]
}

Создание задания подготовки

Чтобы включить подготовку, сначала необходимо создать задание. Используйте следующий запрос, чтобы создать задание подготовки. Используйте templateId из предыдущего шага при указании шаблона, который будет использоваться для задания.

Запросить

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Content-type: application/json

{ 
    "templateId": "aws"
}

Response

HTTP/1.1 201 OK
Content-type: application/json

{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "NotConfigured",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    }
}

Шаг 3. Авторизация доступа

Проверка подключения к приложению

Проверьте соединение со сторонним приложением. Следующий пример предназначен для приложения, для которого требуется секрет клиента и токен секрета. Для каждого приложения предъявляются отдельные требования. В приложениях часто используется базовый адрес вместо секрета клиента. Чтобы определить, какие учетные данные требуются для приложения, перейдите на страницу настройки подготовки приложения и в режиме разработчика нажмите кнопку Проверить подключение. В сетевом трафике будут отображаться параметры, используемые для учетных данных. Полный список учетных данных см. в разделе synchronizationJob: validateCredentials. Большинство приложений, например Azure Databricks, используют BaseAddress и SecretToken. BaseAddress называется URL-адресом клиента в Центре администрирования Microsoft Entra.

Запросить

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

{ 
    "credentials": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx" 
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Response

HTTP/1.1 204 No Content

Сохранение учетных данных

Для настройки подготовки требуется установить доверие между идентификатором Microsoft Entra и приложением, чтобы авторизовать Microsoft Entra, чтобы иметь возможность вызова стороннего приложения. В следующем примере используется приложение, которое требует секрета клиента и маркера секрета. Для каждого приложения предъявляются отдельные требования. Доступные варианты см. в документации по API.

Запросить

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

{ 
    "value": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Response

HTTP/1.1 204 No Content

Шаг 4. Запуск задания подготовки

По завершении настройки задания подготовки используйте следующую команду для запуска задания.

Запросить

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

Response

HTTP/1.1 204 No Content

Шаг 5. Подготовка монитора

Отслеживание статуса задания подготовки

Теперь, когда задание подготовки выполняется, используйте следующую команду для отслеживания хода выполнения. Каждое задание синхронизации в ответе включает состояние текущего цикла подготовки, а также статистику на дату, например количество пользователей и групп, созданных в целевой системе.

Запросить

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

Response

HTTP/1.1 200 OK
Content-type: application/json

{ "value": [
{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "progress": [],
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    },
    "synchronizationJobSettings": [
      {
          "name": "QuarantineTooManyDeletesThreshold",
          "value": "500"
      }
    ]
}
]
}

Мониторинг событий подготовки с помощью журналов подготовки

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

Запросить

GET https://graph.microsoft.com/beta/auditLogs/provisioning

Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#auditLogs/provisioning",
    "value": [
        {
            "id": "gc532ff9-r265-ec76-861e-42e2970a8218",
            "activityDateTime": "2019-06-24T20:53:08Z",
            "tenantId": "7928d5b5-7442-4a97-ne2d-66f9j9972ecn",
            "cycleId": "44576n58-v14b-70fj-8404-3d22tt46ed93",
            "changeId": "eaad2f8b-e6e3-409b-83bd-e4e2e57177d5",
            "action": "Create",
            "durationInMilliseconds": 2785,
            "sourceSystem": {
                "id": "0404601d-a9c0-4ec7-bbcd-02660120d8c9",
                "displayName": "Azure Active Directory",
                "details": {}
            },
            "targetSystem": {
                "id": "cd22f60b-5f2d-1adg-adb4-76ef31db996b",
                "displayName": "AWS Contoso",
                "details": {
                    "ApplicationId": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "AWS Contoso"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            }
            ]
       }
    ]
}

Настройка подготовки с помощью API Microsoft Graph

Шаг 1. Создание приложения коллекции

Получение идентификатора шаблона для приложения в коллекции

Запросить

Response

Создание приложения из коллекции

Запросить

Response

Шаг 2. Создание задания подготовки на основе шаблона

Получение шаблона для соединителя подготовки

Запросить

Response

Создание задания подготовки

Запросить

Response

Шаг 3. Авторизация доступа

Проверка подключения к приложению

Запросить

Response

Сохранение учетных данных

Запросить

Response

Шаг 4. Запуск задания подготовки

Запросить

Response

Шаг 5. Подготовка монитора

Отслеживание статуса задания подготовки

Запросить

Response

Мониторинг событий подготовки с помощью журналов подготовки

Запросить

Response

См. также

Дополнительные ресурсы

Настройка подготовки с помощью API Microsoft Graph

Шаг 1. Создание приложения коллекции

Войдите в Microsoft Graph Explorer (рекомендуется), Postman или любой другой клиент API на ваш выбор.

Получение идентификатора шаблона для приложения в коллекции

Запросить

Response

Создание приложения из коллекции

Запросить

Response

Шаг 2. Создание задания подготовки на основе шаблона

Получение шаблона для соединителя подготовки

Запросить

Response

Создание задания подготовки

Запросить

Response

Шаг 3. Авторизация доступа

Проверка подключения к приложению

Запросить

Response

Сохранение учетных данных

Запросить

Response

Шаг 4. Запуск задания подготовки

Запросить

Response

Шаг 5. Подготовка монитора

Отслеживание статуса задания подготовки

Запросить

Response

Мониторинг событий подготовки с помощью журналов подготовки

Запросить

Response

См. также

Дополнительные ресурсы