Бөлісу құралы:

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

  • Мақала

Область применения: Зеленый круг с белым проверка символом знака. клиенты рабочей силы внешниеБелый круг с серым символом X.клиенты (дополнительные сведения)

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

Внимание

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

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

Совет

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

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

  2. Обзор внешних> удостоверений.>

  3. Выберите Все соединители API, затем выберите Создать соединитель API.

    Снимок экрана: добавление нового соединителя API в внешний идентификатор.

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

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

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

    Снимок экрана: настройка соединителя API.

  7. Выберите Сохранить.

Запрос, отправляемый в 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 в поток пользователя для самостоятельной регистрации.

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

  2. Обзор внешних> удостоверений.>

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

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

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

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

  5. Выберите Сохранить.

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

Соединитель 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 получает HTTP-запрос от идентификатора Microsoft Entra во время пользовательского потока, он может возвращать следующие ответы:

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

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

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

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

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

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

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

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