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

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

Важно!

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

  1. Войдите на портал Azure.

  2. В разделе Службы Azure щелкните Azure Active Directory.

  3. В меню слева щелкните Внешние удостоверения.

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

    Предоставление базовой конфигурации, такой как URL-адрес целевого объекта и отображаемое имя соединителя API, во время создания.

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

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

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

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

  8. Щелкните Сохранить.

Запрос, отправляемый в 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"
}

В запросе могут отправляться только свойства пользователя и настраиваемые атрибуты, перечисленные в таблице Azure Active Directory>Внешние удостоверения>Настраиваемые атрибуты пользователя.

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

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

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

Важно!

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

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

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

  1. Войдите на портал Azure с учетной записью администратора Azure AD.

  2. В разделе Службы Azure щелкните Azure Active Directory.

  3. В меню слева щелкните Внешние удостоверения.

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

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

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

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

  6. Щелкните Сохранить.

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

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

Пример запроса, отправленного в 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 Azure Active Directory в ходе пользовательского сценария, он может вернуть ответы, указанные ниже.

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

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

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

В ответе продолжения API может возвратить утверждения. Если API возвращает утверждение, то это утверждение выполняет следующее действие:

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

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

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

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

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

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

Соединитель API на этом этапе в процессе регистрации вызывается после страницы сбора атрибутов, если она имеется. Этот шаг всегда вызывается перед созданием учетной записи пользователя в Microsoft Azure Active Directory.

Пример запроса, отправленного в 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 Azure Active Directory в ходе пользовательского сценария, он может вернуть ответы, указанные ниже.

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

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

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

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

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

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was a problem with your request. You are not able to sign up at this time.",
}

Параметр Тип Обязательно Описание
version Строка Да Версия интерфейса API.
action Строка Да Значением должно быть 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.",
}
Параметр Тип Обязательно Описание
version Строка Да Версия интерфейса API.
action Строка Да Необходимое значение: ValidationError.
status Целое число/строка Да Должен иметь значение 400 или "400" для ответа ValidationError (Ошибка при проверке).
userMessage Строка Да Сообщение, отображаемое для пользователя.

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

Дальнейшие действия