Использование соединителей API для настройки и расширения потоков пользователей регистрации и настраиваемых политик с помощью внешних источников данных удостоверений

Обзор

Разработчики и ИТ-администраторы могут использовать соединители API для интеграции процессов регистрации пользователей с REST API, чтобы настроить интерфейс регистрации и интегрировать его с внешними системами. Например, используя соединители API, вы можете:

• Проверять входные данные пользователя. Проверять на наличие некорректных или недопустимых пользовательских данных. Например, можно сверить данные, предоставленные пользователем, с существующими данными во внешнем хранилище данных или в списке разрешенных значений. Если значение не является допустимым, можно попросить пользователя предоставить допустимые данные или запретить пользователю продолжать процесс регистрации.
• Проверять удостоверения пользователей. Воспользуйтесь службой проверки личности или внешними источниками данных удостоверений, чтобы добавить дополнительный уровень безопасности к решениям о создании учетных записей.
• Выполнить интеграцию с пользовательским рабочим процессом утверждения. Подключиться к пользовательской системе утверждения для управления и настройки ограничений процесса создания учетной записи.
• Дополнять маркеры атрибутами из внешних источников. Обогащение маркеров атрибутами пользователя из источников, которые являются внешними для Azure AD B2C, таких как облачные системы, пользовательские хранилища пользователей, пользовательские системы разрешений, устаревшие службы удостоверений и многое другое.
• Перезаписать атрибуты пользователя. Переформатировать или присвоить значение атрибуту, полученному от пользователя. Например, если пользователь вводит имя только строчными или заглавными буквами, вы можете изменить его формат, оставив прописной только первую букву.
• Запускать пользовательскую бизнес-логику. Можно активировать события нисходящего потока в облачных системах для отправки push-уведомлений, обновления корпоративных баз данных, управления разрешениями, аудита баз данных и выполнения других настраиваемых действий.

Соединитель API предоставляет Azure AD B2C информацию, необходимую для вызова конечной точки API путем определения URL-адреса конечной точки HTTP и проверки подлинности вызова API. После настройки соединителя API его можно включить для определенных этапов пользовательского процесса. Когда пользователь достигает этого этапа в процессе регистрации, выполняется вызов соединителя API, который представляется как запрос HTTP POST к API; при этом отправляются сведения о пользователе ("утверждения") в качестве пар "ключ-значение" в текстовой области файла JSON. Отклик API может влиять на выполнение пользовательского процесса. Например, отклик API может заблокировать регистрацию пользователя. Необходимо попросить пользователя повторно ввести сведения или перезаписать атрибуты пользователя.

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

Существует три точки в пользовательском процессе, где можно включить соединитель API.

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

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

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

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

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

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

• Проверьте входные данные пользователя и попросите пользователя повторно отправить данные.
• Заблокируйте регистрации пользователя на основе данных, указанных пользователем.
• Проверьте удостоверение пользователя.
• Запросите к внешним системам существующие данные о пользователе, чтобы вернуть их в маркер приложения или сохранить в Microsoft Entra идентификаторе.

Перед отправкой маркера (предварительная версия)

Соединитель API на этом этапе процесса регистрации в системе или входа в нее вызывается перед выдачей маркера. Далее приведены примеры сценариев, которые можно включить на этом шаге:

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

Инфраструктуру Identity Experience Framework, лежащая в основе Azure Active Directory B2C (Azure AD B2C), можно интегрировать с RESTful API в пути взаимодействия пользователя. В этой статье показано, как создать путь взаимодействия пользователя, взаимодействующий со службой RESTful, с помощью технического профиля RESTful.

Azure AD B2C позволяет добавлять собственную бизнес-логику в пути взаимодействия пользователя с помощью вызова службы RESTful. Identity Experience Framework позволяет отправлять и получать данные от службы RESTful для обмена утверждениями. Например, администратор может сделать следующее:

• Использовать внешний источник данных удостоверений для проверки данных, введенный пользователем. Например, вы можете проверить, существует ли адрес электронной почты, предоставленный пользователем, в базе данных клиента, и, если нет, вывести ошибку. Соединители API также можно рассматривать как способ поддержки исходящих веб-перехватчиков, так как вызов выполняется при возникновении события, например при регистрации.
• Обрабатывать утверждения. Если пользователь вводит имя только строчными или только заглавными буквами, REST API может изменить его формат, оставив прописной только первую букву, и вернуть его в Azure AD B2C. Но при использовании настраиваемой политики предпочтительнее будет ClaimsTransformations, а не вызов RESTful API.
• Динамическое обогащение данных пользователя за счет дальнейшей интеграции с корпоративными бизнес-приложениями. Например, служба RESTful может получить адрес электронной почты пользователя, обратиться к базе данных клиента и вернуть в Azure AD B2C номер личного счета пользователя. Затем возвращаемые утверждения могут храниться в учетной записи Microsoft Entra пользователя, оцениваться на следующих шагах оркестрации или включаться в маркер доступа.
• Запускать пользовательскую бизнес-логику. Вы можете отправлять push-уведомления, обновлять корпоративные базы данных, запускать процесс переноса пользователей, управлять разрешениями, производить аудит баз данных и выполнять любые другие рабочие процессы.

Вызов службы RESTful

Взаимодействие включает в себя обмен утверждениями между REST API и Azure AD B2C. Интеграцию со службами RESTful можно спроектировать одним из следующих способов:

• Технический профиль проверки. Вызов службы RESTful происходит в техническом профиле проверки указанного самоподтвержденного технического профиля или в элементе управления отображением проверки для элемента управления отображением. Этот профиль проверяет данные, предоставленные пользователем, в начале пути взаимодействия пользователя. С помощью технического профиля проверки вы можете:

  • отправлять утверждения в REST API;
  • проверять утверждения и инициировать пользовательские сообщения об ошибках;
  • отправлять утверждения из REST API на последующие шаги оркестрации.

• Обмен утверждениями. Прямой обмен утверждениями можно настроить, вызвав технический профиль REST API непосредственно из этапа оркестрации пути взаимодействия пользователя. Может только:

  • отправлять утверждения в REST API;
  • проверять утверждения и инициировать пользовательские сообщения об ошибках, которые возвращаются в приложение;
  • отправлять утверждения из REST API на последующие шаги оркестрации.

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

• во время входа в систему перед тем, как Azure AD B2C проверит учетные данные;
• сразу после входа в систему;
• перед тем как Azure AD B2C создаст учетную запись в каталоге;
• после того как Azure AD B2C создаст учетную запись в каталоге;
• перед тем как Azure AD B2C выдаст маркер доступа.

Отправка данных

В техническом профиле RESTful элемент InputClaims содержит список утверждений для отправки в службу RESTful. Вы можете связать имя утверждения с именем, определенным в службе RESTful, задать значение по умолчанию и использовать сопоставители утверждений.

Настроить отправку входных утверждений в поставщик утверждений RESTful можно с помощью атрибута SendClaimsIn. Вы можете выбрать

• Body — отправляется в тексте HTTP-запроса POST в формате JSON.
• Form — отправляется в тексте HTTP-запроса POST в формате пар "ключ-значение", разделенных символом амперсанда (&).
• Header — отправляется в заголовке HTTP-запроса GET.
• QueryString — отправляется в строке HTTP-запроса GET.

Если параметр Body настроен, технический профиль REST API позволяет отправлять в конечную точку сложные полезные данные JSON. Дополнительные сведения см. в разделе Отправка полезных данных JSON.

Получение данных

Элемент OutputClaimsтехнического профиля RESTful содержит список утверждений, возвращаемых REST API. Может потребоваться сопоставить имя утверждения, определенное в вашей политике, с именем, определенным в REST API. Вы также можете добавить утверждения, которые не возвращаются поставщиком удостоверений REST API, установив атрибут DefaultValue.

Выходные утверждения, анализируемые поставщиком утверждений RESTful, всегда должны анализироваться как плоский текст JSON в ответе, например:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Выходные утверждения должны выглядеть так, как в следующем фрагменте XML:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Обработка значений NULL

Значение NULL в базе данных используется, если значение в столбце неизвестно или отсутствует. Не включайте ключи JSON со значением null . В следующем примере для адреса электронной почты возвращается значение null:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Если элемент имеет значение null, возможны следующие варианты:

• Пропуск пары "ключ — значение" из JSON.
• Возврат значения, соответствующего типу данных утверждения Azure AD B2C. Например, для типа данных string возвращается пустая строка "". Для типа данных integer возвращается нулевое значение 0. Для типа данных dateTime возвращается минимальное значение 1970-00-00T00:00:00.0000000Z.

Следующий пример демонстрирует, как обрабатывать значение NULL. Адрес электронной почты из JSON пропускается:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Анализ вложенного тела JSON

Чтобы проанализировать вложенный ответный текст JSON, установите для метаданных ResolveJsonPathsInJsonTokens значение true. В выходном утверждении задайте для PartnerClaimType элемент пути JSON, который нужно вывести.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Выходные утверждения должны выглядеть так, как в следующем фрагменте XML:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Локализация REST API

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

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Обработка сообщений об ошибке

Rest API может потребоваться вернуть сообщение об ошибке, например "Пользователь не найден в системе CRM". При возникновении ошибки REST API должен вернуть сообщение об ошибке HTTP 409 (код состояния ответа на конфликт). Дополнительные сведения см. в описании технического профиля RESTful.

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

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

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

Примеры использования технического профиля RESTful см. в следующих статьях:

• Пошаговое руководство. Добавление соединителя API в пользовательский сценарий регистрации
• Пошаговое руководство. Добавление возможности обмена утверждениями REST API в настраиваемые политики в Azure Active Directory B2C
• Защита служб REST API
• Общие сведения Технический профиль RESTful