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

Статья
02/05/2024

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

Внимание

Начиная с 12 июля 2021 года, если клиенты Microsoft Entra B2B настроили новые интеграции Google для самостоятельной регистрации для своих пользовательских или бизнес-приложений, проверка подлинности с удостоверениями Google не будет работать, пока проверки подлинности не будут перемещены в системные веб-представления. Подробнее.
30 сентября 2021 года Google прекращает поддержку входа через встроенные веб-представления. Если ваши приложения проходят проверку подлинности пользователей с внедренным веб-представлением и используете федерацию Google с Azure AD B2C или Microsoft Entra B2B для приглашений внешних пользователей или самостоятельной регистрации, пользователи Google Gmail не смогут пройти проверку подлинности. Подробнее.

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

Совет

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

Войдите в Центр администрирования Microsoft Entra как минимум пользователь Администратор istrator.
Обзор внешних> удостоверений.>
Выберите Все соединители API, затем выберите Создать соединитель API.
Укажите отображаемое имя для вызова. Например, Проверка состояния утверждения.
Укажите URL-адрес конечной точки для вызова API.
Выберите Тип проверки подлинности и настройте сведения проверки подлинности для вызова API. Узнайте, как защитить свой соединитель API.
Выберите Сохранить.

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

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

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

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "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"
}

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

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

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

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

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

Внимание

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

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

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

Войдите в Центр администрирования Microsoft Entra как минимум пользователь Администратор istrator.
Обзор внешних> удостоверений.>
Выберите Пользовательские сценарии, затем выберите сценарий пользователя, к которому надо добавить соединитель API.
Выберите Соединители API, затем выберите конечные точки API, которые надо вызывать в пользовательском потоке при выполнении действий, описанных ниже.
- После установления федерации с поставщиком удостоверений во время регистрации
- Перед созданием пользователя
Выберите Сохранить.

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

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

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "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 возвращает утверждение, то это утверждение выполняет следующее действие:

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

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

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

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

См. пример блокирующего ответа.

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

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

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

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "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 отвечает с ответом на ошибку проверки, поток пользователя остается на странице коллекции атрибутов и 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
}

Параметр	Type	Обязательно	Описание
версия	Строка	Да	Версия интерфейса API.
действие	Строка	Да	Необходимое значение: `Continue`.
<builtInUserAttribute>	<attribute-type>	No	Значения могут сохраняться в каталоге, если для них выбраны настройки Получаемое утверждение в конфигурации соединителя API и Атрибуты пользователя для потока пользователя. Значения могут возвращаться в токене, если он выбран в качестве Утверждения приложения.
<extension_{идентификатор_приложения_расширений}_CustomAttribute>	<attribute-type>	No	Утверждение не должно содержать `_<extensions-app-id>_`, это необязательно. Возвращаемые значения могут перезаписывать значения, полученные от пользователя.

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

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

Параметр	Type	Обязательно	Описание
версия	Строка	Да	Версия интерфейса API.
действие	Строка	Да	Значением должно быть `ShowBlockPage`
userMessage	Строка	Да	Сообщение, отображаемое для пользователя.

Отображение блокирующего ответа в интерфейсе пользователя

Пример изображения: интерфейс пользователя после возврата блокирующего ответа API.

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

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

Параметр	Type	Обязательно	Описание
версия	Строка	Да	Версия интерфейса API.
действие	Строка	Да	Необходимое значение: `ValidationError`.
статус	Целое число/строка	Да	Должен иметь значение `400` или `"400"` для ответа ValidationError (Ошибка при проверке).
userMessage	Строка	Да	Сообщение, отображаемое для пользователя.

Примечание.

Код состояния HTTP должен иметь значение 400 в дополнение к значению "status" в тексте ответа.

Отображение ответа об ошибке при проверке в интерфейсе пользователя

Пример изображения: отображение ответа об ошибке при проверке в интерфейсе пользователя.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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