Используйте подключения 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 ID.

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

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

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

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

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

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

• Текст, отправленный в тексте ЗАПРОСА HTTP POST в формате JSON.
• Форма, отправленная в теле HTTP POST-запроса в формате пары «ключ-значение», разделенной амперсандом (&).
• Заголовок, отправленный в заголовке 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": "[email protected]",
  "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 вернуть минимальное значение 0001-01-01T00: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 protected]"
        }
      ]
    }
  }
],

Утверждения на выходе должны выглядеть как следующий фрагмент 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
• Вызов REST API с помощью пользовательской политики Azure Active Directory B2C