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

Статья
05/23/2023

Для начала с помощью селектора Choose a policy type (Выбрать тип политики) выберите тип пользовательской политики. Azure Active Directory B2C предлагает два метода определения способа взаимодействия пользователей с вашими приложениями: с помощью предопределенных потоков пользователей или полностью настраиваемых пользовательских политик. Действия, которые необходимо выполнить, отличаются для каждого метода.

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

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

Примечание.

Эта функция предоставляется в общедоступной предварительной версии.

Вы можете создать конечную точку API, используя один из наших примеров.

Необходимые компоненты

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

Выполните шаги, описанные в статье Начало работы с настраиваемыми политиками в Azure Active Directory B2C.
Зарегистрируйте веб-приложение.

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

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

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

Войдите на портал Azure.
В разделе Службы Azure выберите Azure AD B2C.
Выберите Соединители API, затем — Создать соединитель API.
Укажите отображаемое имя для вызова. Например, Обогащение токена из внешнего источника.
Укажите URL-адрес конечной точки для вызова API.
Выберите Тип проверки подлинности и настройте сведения проверки подлинности для вызова API. Узнайте, как защитить свой соединитель API.
Выберите Сохранить.

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

Чтобы добавить соединитель API в пользовательский сценарий, выполните действия, описанные ниже.

Войдите на портал Azure.
В разделе Службы Azure выберите Azure AD B2C.
Выберите Пользовательские сценарии, затем выберите сценарий пользователя, к которому надо добавить соединитель API.
Выберите Соединители API, затем выберите конечные точки API, которые надо вызывать в пользовательском потоке при выполнении действия Перед отправкой маркера (предварительная версия).
Выберите Сохранить.

Этот шаг существует только для пользовательских потоков регистрации и входа (рекомендуется), регистрации (рекомендуется) и входа (рекомендуется).

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

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

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

Утверждения, отправляемые в API, зависят от заданной для пользователя информации. В запросе можно отправлять только свойства пользователя и настраиваемые атрибуты, перечисленные в интерфейсе Azure AD B2C>Атрибуты пользователя. Настраиваемые атрибуты в каталоге имеют формат extension_<extensions-app-id>_CustomAttribute. Ваш API должен быть рассчитан на прием утверждений в таком же сериализованном формате. Дополнительные сведения о настраиваемых атрибутах см. в разделе Определение настраиваемых атрибутов в Azure AD B2C. Кроме того, на этом шаге эти утверждения обычно отправляются во всех запросах.

Языковые стандарты пользовательского интерфейса (ui_locales) — языковые стандарты пользователя, настроенные на его устройстве. Их можно использовать в API для возврата ответов для пользователей из разных стран.
Шаг (step) — шаг или точка в потоке пользователя, для которого был вызван соединитель API. Значение для этого шага
Идентификатор клиента (client_id) — значение appId приложения, в котором выполняется проверка подлинности пользователя в потоке пользователя. Это не значение appId приложения ресурса в маркерах доступа.
objectId — идентификатор пользователя. Его можно использовать для запроса сведений о пользователе у нижестоящих служб.

Важно!

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

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

Когда веб-API получает HTTP-запрос от идентификатора Microsoft Entra ID во время пользовательского потока, он может вернуть "ответ продолжения".

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

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

Примечание.

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

Пример отклика

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

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	Значения могут возвращаться в токене, если он выбран в качестве Утверждения приложения.
<extension_{идентификатор_приложения_расширений}_CustomAttribute>	<attribute-type>	No	Утверждение необязательно должно содержать `_<extensions-app-id>_`: это значение является необязательным. Значения могут возвращаться в токене, если он выбран в качестве Утверждения приложения.

В этом сценарии вы обогатите данные токена пользователя за счет интеграции с корпоративным бизнес-процессом. Во время регистрации или входа с использованием локальной или федеративной учетной записи Azure AD B2C вызывает REST API для получения расширенных данных профиля пользователя из удаленного источника данных. В этом примере Azure AD B2C отправляет уникальный идентификатор пользователя — objectId. Затем REST API возвращает значение суммы остатка на счете пользователя (случайное число). Используйте этот пример в качестве отправной точки для интеграции с собственной системой CRM, маркетинговой базой данных или любым рабочим бизнес-процессом. Взаимодействие можно также реализовать как технический профиль проверки. Этот вариант подходит, когда REST API будет проверять данные на экране и возвращать утверждения. Дополнительные сведения см. в статье Руководство по добавлению соединителя API к процессу пользовательского входа.

Необходимые компоненты

Выполните шаги, описанные в статье Начало работы с настраиваемыми политиками в Azure Active Directory B2C. Для регистрации и входа с использованием локальных учетных записей необходимо иметь рабочую настраиваемую политику.
Прочтите статью Интеграция обмена утверждениями REST API в настраиваемую политику Azure AD B2C.

Подготовка конечной точки REST API

Для работы с этим пошаговым руководством у вас должен быть REST API, который проверяет, зарегистрирован ли идентификатор Azure AD B2C objectId пользователя в серверной системе. Если идентификатор зарегистрирован, REST API возвращает значение суммы остатка на счете. В противном случае REST API регистрирует новый счет в каталоге и возвращает начальный остаток на счете 50.00. В следующем коде JSON показаны данные, которые Azure AD B2C отправит в конечную точку REST API.

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

После того как REST API проверит данные, он должен вернуть HTTP 200 (ОК) со следующими данными JSON:

{
    "balance": "760.50"
}

В рамках этой статьи настройка конечной точки REST API не рассматривается. Вы создали пример Функций Azure. Полный код функции Azure доступен на сайте GitHub.

Определение утверждений

Утверждение предоставляет временное хранилище данных на время выполнения политики Azure AD B2C. Утверждения можно объявить в разделе схемы утверждений.

Откройте файл расширения политики. Например, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Найдите элемент BuildingBlocks. Если такой элемент не существует, добавьте его.
Найдите элемент ClaimsSchema. Если такой элемент не существует, добавьте его.
Добавьте следующие утверждения в элемент ClaimsSchema.

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Добавление технического профиля RESTful API

Технический профиль RESTful обеспечивает поддержку взаимодействия с вашей собственной службой RESTFUL. Azure AD B2C отправляет данные в службу RESTful в виде коллекции InputClaims ответы в виде коллекции OutputClaims. Найдите элемент ClaimsProviders в файле TrustFrameworkExtensions.xml и добавьте новый поставщик утверждений, как показано ниже.

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

В этом примере userLanguage отправляется в службу REST как lang в полезных данных JSON. Значение утверждения userLanguage содержит текущий идентификатор языка пользователя. Дополнительные сведения см. в статье об арбитрах утверждений.

Настройка технического профиля RESTful API

После развертывания REST API задайте метаданные технического профиля REST-GetProfile в соответствии с собственными REST API, включая:

ServiceUrl. Задайте URL-адрес конечной точки REST API.
SendClaimsIn. Укажите, как отправляются входящие утверждения поставщику утверждений RESTful.
AuthenticationType. Задайте тип проверки подлинности, выполняемой поставщиком утверждений RESTful, например Basic или ClientCertificate.
AllowInsecureAuthInProduction. В рабочей среде для этих метаданных укажите значение false.

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

Добавление шага оркестрации

В путях взаимодействия пользователя указываются явные пути, через которые политика позволяет приложению, основанному на утверждениях, предоставлять пользователю требуемые утверждения. Путь взаимодействия пользователя представляется в виде последовательности оркестрации, которая должна быть соблюдена для успешного выполнения транзакции. Можно добавлять или удалять шаги оркестрации. Здесь вы добавите новый шаг оркестрации, который будет использоваться для расширения сведений, предоставленных приложению после регистрации или входа пользователя путем вызова REST API.

Откройте базовый файл политики. Например, SocialAndLocalAccounts/TrustFrameworkBase.xml.
Найдите элемент <UserJourneys>. Скопируйте весь элемент, а затем удалите его.
Откройте файл расширения политики. Например, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Вставьте <UserJourneys> в файл расширений после закрытия элемента <ClaimsProviders>.

Найдите <UserJourney Id="SignUpOrSignIn"> и добавьте следующий шаг оркестрации перед последним.

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>

Выполните рефакторинг последнего шага оркестрации, изменив Order на 8. Последние два шага оркестрации должны выглядеть следующим образом:

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
<OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />

Повторите два последних шага для путей взаимодействия пользователя ProfileEdit и PasswordReset.

Включение утверждения в токен

Чтобы вернуть утверждение balance в приложение проверяющей стороны, добавьте выходное утверждение в файл SocialAndLocalAccounts/SignUpOrSignIn.xml. При добавлении выходного утверждения утверждение включается в токен после успешного пути взаимодействия пользователя и будет отправлено в приложение. Измените элемент технического профиля в разделе проверяющей стороны, добавив balance в качестве выходного утверждения.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Повторите этот шаг для путей взаимодействия пользователя ProfileEdit.xml и PasswordReset.xml. Сохраните измененные файлы: TrustFrameworkBase.xml и TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml и PasswordReset.xml.

Проверка пользовательской политики

Войдите на портал Azure.
Если у вас есть доступ к нескольким клиентам, выберите значок Параметры в верхнем меню, чтобы переключиться на клиент Azure AD B2C из меню каталогов и подписок.
Выберите Все службы в левом верхнем углу окна портала Azure, а затем найдите и выберите Регистрация приложений.
Выберите Инфраструктура процедур идентификации.
Выберите "Отправить настраиваемую политику", а затем отправьте измененные файлы политики: TrustFrameworkBase.xml и TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml и PasswordReset.xml.
Выберите отправленную вами политику регистрации или входа и нажмите кнопку Выполнить.
Вы сможете зарегистрироваться, используя адрес электронной почты и учетную запись Facebook.
Токен, отправленный обратно в ваше приложение, включает утверждение balance.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

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

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

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

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

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

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

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

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

Откройте Azure AD B2C.
В разделе Действия выберите Журналы аудита.
Отфильтруйте представление списка: в качестве даты выберите нужный интервал времени, а в качестве действия — вызов API в потоке пользователя.
Проверьте отдельные записи в журнале. Каждая строка представляет собой попытку вызова соединителя API в потоке пользователя. Если вызов API завершается неудачей и происходит повторная попытка, она также отражается одной строкой. Атрибут numberOfAttempts указывает, сколько раз вызывался API. Возможные значения — 1 и 2. Другие сведения о вызове API подробно представлены в журналах.

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

Начало работы с нашими примерами
Защита соединителя API

Из следующих статей вы узнаете, как защитить API-интерфейсы.

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

Необходимые компоненты

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

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

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

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

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

Пример отклика

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

Необходимые компоненты

Подготовка конечной точки REST API

Определение утверждений

Добавление технического профиля RESTful API

Настройка технического профиля RESTful API

Добавление шага оркестрации

Включение утверждения в токен

Проверка пользовательской политики

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

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

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

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

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

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

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

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