Добавление соединителя API в поток пользователя

Применяется: Арендаторы рабочей силы Внешние арендаторы (дополнительные сведения)

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

Создание соединителя API

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор пользователя.

2. Перейдите в Entra ID>Внешние идентификаторы>Обзор.

3. Выберите все соединители API и выберите новый соединитель API.

   

4. Укажите отображаемое имя для вызова. Например, проверьте состояние утверждения.

5. Укажите URL-адрес конечной точки для вызова API.

6. Выберите тип проверки подлинности и настройте сведения о проверке подлинности для вызова API. Узнайте, как защитить соединитель API.

   

7. Нажмите кнопку "Сохранить".

Запрос, отправляемый в API

Соединитель API материализуется как HTTP-запрос POST, отправляя атрибуты пользователя ("утверждения") в виде пар "ключ-значение" в формате JSON. Атрибуты сериализуются аналогично свойствам пользователя Microsoft Graph .

Пример запроса

POST <API-endpoint>
Content-type: application/json

{
 "email": "[email protected]",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Только пользовательские свойства и настраиваемые атрибуты, перечисленные в Entra ID>External Identities>Overview>Custom user attributes experience, доступны для отправки в запросе.

Настраиваемые атрибуты существуют в формате extension_<extensions-app-id>_AttributeName в каталоге. Ваш API должен быть рассчитан на прием утверждений в таком же сериализованном формате. Дополнительные сведения о пользовательских атрибутах см. в разделе "Определение настраиваемых атрибутов" для потоков самостоятельной регистрации.

Кроме того, утверждения обычно отправляются во всех запросах:

• Языковые параметры пользовательского интерфейса ("ui_locales') — языковые параметры конечного пользователя, настроенные на своем устройстве, которые API может использовать для возврата международных ответов.

• Адрес электронной почты ('электронная почта') или идентификаторы ('идентификаторы') — эти утверждения могут использоваться вашим API для идентификации конечного пользователя, который выполняет проверку подлинности в приложении.

Включение соединителя API в пользовательском сценарии

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

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор пользователя.

2. Перейдите в Entra ID>Внешние идентификаторы>Обзор.

3. Выберите потоки пользователей и выберите поток пользователя, к которому нужно добавить соединитель API.

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

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

   

5. Нажмите кнопку "Сохранить".

После установления федерации с поставщиком удостоверений во время регистрации

Соединитель API на этом шаге в процессе регистрации вызывается сразу после проверки подлинности пользователя с помощью поставщика удостоверений (например, Google, Facebook или идентификатора Microsoft Entra). Этот шаг предшествует странице коллекции атрибутов, которая представляет собой форму, представленную пользователю для сбора атрибутов пользователя.

Пример запроса, отправленного в API на этом шаге

POST <API-endpoint>
Content-type: application/json

{
 "email": "[email protected]",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Точные утверждения, отправленные API, зависят от того, какие сведения предоставляются поставщиком удостоверений. Утверждение 'email' (адрес электронной почты) отправляется всегда.

Ожидаемые типы ответов из веб-API на этом шаге

Когда веб-API получает HTTP-запрос от идентификатора Microsoft Entra во время пользовательского потока, он может возвращать следующие ответы:

• Ответ продолжения
• Блокирующий ответ

Ответ продолжения

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

API в ответе на продолжение может вернуть следующее утверждение:

• Перед заполнением поля ввода на странице коллекции атрибутов.

См. пример продолжающего ответа.

Блокирующий ответ

Блокирующий ответ завершает пользовательский сценарий. API может специально выдавать блокирующий ответ, чтобы остановить продолжение потока пользователя, отображая страницу блокировки пользователю. На странице блокировки отображается сообщение userMessage, предоставленное API-интерфейсом.

См. пример ответа на блокировку.

Перед созданием пользователя

Соединитель API на этом этапе процесса регистрации вызывается после страницы коллекции атрибутов (если есть). Этот шаг всегда вызывается перед созданием учетной записи пользователя в идентификаторе Microsoft Entra.

Пример запроса, отправленного в API на этом шаге

POST <API-endpoint>
Content-type: application/json

{
 "email": "[email protected]",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

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

Ожидаемые типы ответов из веб-API на этом шаге

Когда веб-API получает HTTP-запрос от идентификатора Microsoft Entra во время пользовательского потока, он может возвращать следующие ответы:

• Ответ продолжения
• Блокирующий ответ
• Ответ проверки

Ответ продолжения

Ответ продолжения указывает, что пользовательский сценарий должен перейти на следующий шаг: создание пользователя в каталоге.

В ответе на запрос о продолжении API может вернуть претензию, которая:

• Переопределяет любое значение, уже присвоенное требованию на странице коллекции атрибутов.

См. пример ответа с продолжением.

Блокирующий ответ

Блокирующий ответ завершает пользовательский сценарий. API может специально выдавать блокирующий ответ, чтобы остановить продолжение потока пользователя, отображая страницу блокировки пользователю. На странице блокировки отображается сообщение userMessage, предоставленное API-интерфейсом.

См. пример ответа на блокировку.

Ответ об ошибке при проверке

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

См. пример ответа на ошибку проверки.

Примеры ответов

Пример ответа продолжения

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

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Пример блокирующего ответа

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Взаимодействие с конечным пользователем с ответом на блокировку

Пример ответа об ошибке при проверке

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Взаимодействие с конечным пользователем с ответом на ошибку проверки

Рекомендации и устранение неполадок

Использование бессерверных облачных функций

Бессерверные функции, такие как триггеры HTTP в Функциях Azure, предоставляют способ создания конечных точек API для использования с соединителем API. Вы можете использовать бессерверную облачную функцию для выполнения логики проверки и ограничения регистрации в определенных доменах электронной почты. Бессерверная облачная функция также может вызывать другие веб-API, хранилища данных и другие облачные службы для реализации сложных сценариев.

Рекомендации

Убедитесь в следующем:

• Ваша API следует условиям запросов и ответов, как было описано ранее.
• URL-адрес конечной точки соединителя API указывает на правильную конечную точку API.
• API явным образом проверяет полученные утверждения, которые ему необходимы, на наличие в них значений NULL.
• Ваш API реализует метод проверки подлинности, описанный в разделе "Обезопасьте ваш API Connector".
• API реагирует на операции как можно быстрее, чтобы обеспечить работу пользовательского интерфейса без задержек.
  • Идентификатор Microsoft Entra ожидает не более 20 секунд , чтобы получить ответ. Если ни один из них не получен, он выполняет еще одну попытку (повторить) при вызове API.
  • Если используется бессерверная функция или масштабируемая веб-служба, реализуйте план размещения, по которому API в рабочей среде постоянно будет в "пробужденном" или "теплом" состоянии. Для функций Azure рекомендуется использовать как минимум план "Премиум".
• Обеспечьте высокую доступность вашего API.
• Отслеживайте и оптимизируйте производительность нижестоящих API, баз данных и других зависимостей вашего API.
• Конечные точки должны соответствовать требованиям безопасности TLS и шифров Microsoft Entra. Дополнительные сведения см. в разделе о требованиях к tls и набору шифров.

Использование ведения журналов

Как правило, полезно использовать средства ведения журнала, включенные службой веб-API, например Application Insights, для мониторинга API для непредвиденных кодов ошибок, исключений и низкой производительности.

• Отслеживайте коды состояния HTTP, отличные от HTTP 200 и 400.
• Код состояния HTTP 401 или 403 обычно указывает на проблему, связанную с проверкой подлинности. Дважды проверьте настроенный уровень проверки подлинности API и соответствующую конфигурацию в соединителе API.
• При необходимости используйте более агрессивные уровни ведения журнала (например, "трассировка" или "отладка").
• Отслеживайте работу API на предмет больших значений для времени отклика.

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

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