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

2025-05-03

Это важно

Начиная с 1 мая 2025 г. Azure AD B2C больше не будет доступен для приобретения для новых клиентов. Дополнительные сведения см. в разделе "Вопросы и ответы".

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

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

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

Замечание

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

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

Предпосылки

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

Выполните действия, описанные в статье "Начало работы с настраиваемыми политиками в Active Directory B2C". В этом руководстве описано, как обновить пользовательские файлы политики для использования конфигурации клиента Azure AD 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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

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

Языковые стандарты пользовательского интерфейса (ui_locales) — языковые стандарты пользователя, настроенные на его устройстве. Их можно использовать в API для возврата ответов для пользователей из разных стран.
Шаг ('step') — шаг или этап в пользовательском потоке, для которого был вызван соединитель API. Значение для этого шага — ''
Идентификатор клиента ('client_id') — 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
}

Параметр	Тип	Обязательно	Описание
версия	Струна	Да	Версия вашего API.
действие	Струна	Да	Необходимое значение: `Continue`.
<встроенныйПользовательскийАтрибут>	<атрибут-тип>	нет	Их можно вернуть в токене, если они выбраны как утверждение приложения.
<extension_{идентификатор_приложения_расширений}_CustomAttribute>	<атрибут-тип>	нет	В утверждении не обязательно должно содержаться `_<extensions-app-id>_`, это необязательно. Их можно вернуть в токене, если они выбраны как утверждение приложения.

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

Предпосылки

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

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

В этом пошаговом руководстве у вас должен быть REST API, который проверяет и подтверждает, зарегистрирован ли идентификатор объекта Azure AD B2C пользователя в вашей серверной системе. При регистрации 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>

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

Технический профиль 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 языка. Дополнительные сведения см. в разделе "Сопоставитель утверждений".

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

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

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

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

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

В путях взаимодействия пользователя указываются явные пути, через которые политика позволяет приложению, основанному на утверждениях, предоставлять пользователю требуемые утверждения. Путь взаимодействия пользователя представляется в виде последовательности оркестрации, которая должна быть соблюдена для успешного выполнения транзакции. Вы можете добавить или вычесть шаги оркестрации. В этом случае вы добавите новый шаг оркестрации, который используется для расширения сведений, предоставленных приложению после регистрации или входа пользователя с помощью вызова 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.
Если у вас есть доступ к нескольким клиентам, щелкните значок "Параметры " в верхнем меню, чтобы переключиться на клиент Microsoft Entra из меню каталогов и подписок .
Выберите все службы в левом верхнем углу портала Azure, а затем найдите и выберите регистрацию приложений.
Выберите Identity Experience Framework.
Выберите "Отправить настраиваемую политику", а затем отправьте измененные файлы политики: 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/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "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"
  ...
}

Дальнейшие шаги

Начните с наших примеров.
Защита соединителя API

Сведения о защите API см. в следующих статьях:

Поделиться через

Предпосылки

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

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

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

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

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

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

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

Предпосылки

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

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

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

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

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

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

Проверка настраиваемой политики

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

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

Лучшие практики

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

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

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

Поделиться через

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

Предпосылки

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

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

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

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

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

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

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

Предпосылки

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

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

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

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

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

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

Проверка настраиваемой политики

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

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

Лучшие практики

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

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

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

Дальнейшие шаги

Обратная связь

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