Конечная точка UserInfo

Статья
01/11/2024

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

Конечная точка UserInfo предусмотрена стандартной спецификацией OpenID Connect (OIDC) и разработана для возврата утверждений о пользователе, который прошел проверку подлинности. Конечная точка UserInfo определена в политике проверяющей стороны с помощью элемента EndPoint.

Эта возможность доступна только для пользовательских политик. Чтобы ознакомиться с этапами установки, в предыдущем селекторе выберите Настраиваемая политика.

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

Выполните шаги, описанные в статье Начало работы с настраиваемыми политиками в Azure Active Directory B2C. В этом руководстве описано, как обновить пользовательские файлы политики для использования конфигурации клиента Azure AD B2C.
Если вы еще не зарегистрировали веб-приложение, зарегистрируйте его, выполнив действия, описанные в регистрации веб-приложения.

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

В сведениях о пользователе UserJourney указано следующее:

Авторизация. Конечная точка UserInfo защищена маркером носителя. В заголовке авторизации для конечной точки UserInfo представлен выданный маркер доступа. Политика указывает технический профиль, который проверяет входящий маркер и извлекает утверждения, например objectId пользователя. ObjectId пользователя используется для получения утверждений, возвращаемых в ответе пути конечной точки UserInfo.
Шаг оркестрации:
- Шаг оркестрации используется для сбора сведений о пользователе. В зависимости от утверждений входящего маркера доступа путь пользователя вызывает технический профиль Идентификатора Microsoft Entra для получения данных о пользователе, например чтение пользователя с помощью objectId.
- Дополнительные шаги оркестрации. Вы можете добавить дополнительные шаги оркестрации, например технический профиль REST API, чтобы получить дополнительные сведения о пользователе.
- Поставщик UserInfo. Указывает список утверждений, возвращаемых конечной точкой UserInfo.

Создание конечной точки UserInfo

1. Добавление технического профиля издателя маркера

Откройте файл TrustFrameworkExtensions.xml.
Если он еще не существует, добавьте элемент ClaimsProvider и его дочерние элементы в качестве первого элемента в элементе BuildingBlocks.

Добавьте следующий поставщик утверждений:

<!-- 
<ClaimsProviders> -->
  <ClaimsProvider>
    <DisplayName>Token Issuer</DisplayName>
    <TechnicalProfiles>
      <TechnicalProfile Id="UserInfoIssuer">
        <DisplayName>JSON Issuer</DisplayName>
        <Protocol Name="None" />
        <OutputTokenFormat>JSON</OutputTokenFormat>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <!-- The Below claims are what will be returned on the UserInfo Endpoint if in the Claims Bag-->
        <InputClaims>
          <InputClaim ClaimTypeReferenceId="objectId"/>
          <InputClaim ClaimTypeReferenceId="givenName"/>
          <InputClaim ClaimTypeReferenceId="surname"/>
          <InputClaim ClaimTypeReferenceId="displayName"/>
          <InputClaim ClaimTypeReferenceId="signInNames.emailAddress"/>
        </InputClaims>
      </TechnicalProfile>
      <TechnicalProfile Id="UserInfoAuthorization">
        <DisplayName>UserInfo authorization</DisplayName>
        <Protocol Name="None" />
        <InputTokenFormat>JWT</InputTokenFormat>
        <Metadata>
          <!-- Update the Issuer and Audience below -->
          <!-- Audience is optional, Issuer is required-->
          <Item Key="issuer">https://yourtenant.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/</Item>
          <Item Key="audience">[ "22222222-2222-2222-2222-222222222222", "33333333-3333-3333-3333-333333333333" ]</Item>
          <Item Key="client_assertion_type">urn:ietf:params:oauth:client-assertion-type:jwt-bearer</Item>
        </Metadata>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <OutputClaims>
          <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
          <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email"/>
          <!-- Optional claims to read from the access token. -->
          <!-- <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="given_name"/>
             <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="family_name"/>
             <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name"/> -->
        </OutputClaims>
      </TechnicalProfile>
    </TechnicalProfiles>
  </ClaimsProvider>
<!-- 
</ClaimsProviders> -->

В разделе InputClaims в техническом профиле UserInfoIssuer указаны атрибуты, которые требуется вернуть. Технический профиль UserInfoIssuer вызывается в конце пути взаимодействия пользователя.
Технический профиль UserInfoAuthorization проверяет подпись, имя издателя и аудиторию маркера, а также извлекает утверждение из входящего маркера. Измените следующие метаданные в соответствии со своим окружением:
1. issuer — это значение должно совпадать с утверждением iss в утверждении маркера доступа. Маркеры, выданные Azure AD B2C, используют издатель в формате https://yourtenant.b2clogin.com/your-tenant-id/v2.0/. Дополнительные сведения см. в статье Настройка маркеров в Azure Active Directory B2C.
2. IdTokenAudience — это значение должно совпадать с утверждением aud в утверждении маркера доступа. В Azure AD B2C утверждение aud —это идентификатор приложения проверяющей стороны. Это значение является коллекцией и поддерживает несколько значений с разделителем в виде запятой.
  
  В следующем маркере доступа значение утверждения iss — https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/. Значение утверждения aud — 22222222-2222-2222-2222-222222222222.
```
{
  "exp": 1605549468,
  "nbf": 1605545868,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/",
  "sub": "44444444-4444-4444-4444-444444444444",
  "aud": "22222222-2222-2222-2222-222222222222",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1605545868,
  "auth_time": 1605545868,
  "name": "John Smith",
  "given_name": "John",
  "family_name": "Smith",
  "tid": "11111111-1111-1111-1111-111111111111"
}
```
Элемент OutputClaims в техническом профиле UserInfoAuthorization указывает атрибуты, которые требуется считать из маркера доступа. ClaimTypeReferenceId — это ссылка на тип утверждения. Необязательный параметр PartnerClaimType — это имя утверждения, определенного в маркере доступа.

2. Добавление элемента UserJourney

Элемент UserJourney определяет путь взаимодействия пользователя с приложением. Добавьте элемент UserJourneys, если он не существует. Присвойте UserJourney идентификатор UserInfoJourney.

<!-- 
<UserJourneys> -->
  <UserJourney Id="UserInfoJourney" DefaultCpimIssuerTechnicalProfileReferenceId="UserInfoIssuer">
    <Authorization>
      <AuthorizationTechnicalProfiles>
        <AuthorizationTechnicalProfile ReferenceId="UserInfoAuthorization" />
      </AuthorizationTechnicalProfiles>
    </Authorization>
    <OrchestrationSteps >
      <OrchestrationStep Order="1" Type="ClaimsExchange">
        <Preconditions>
          <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
            <Value>objectId</Value>
            <Action>SkipThisOrchestrationStep</Action>
          </Precondition>
        </Preconditions>
        <ClaimsExchanges UserIdentity="false">
          <ClaimsExchange Id="AADUserReadWithObjectId" TechnicalProfileReferenceId="AAD-UserReadUsingObjectId" />
        </ClaimsExchanges>
      </OrchestrationStep>
      <OrchestrationStep Order="2" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="UserInfoIssuer" />
    </OrchestrationSteps>
  </UserJourney>
<!-- 
</UserJourneys> -->

3. Добавление конечной точки в политику проверяющей стороны

Чтобы добавить конечную точку UserInfo в приложение проверяющей стороны, добавьте элемент Endpoint в файл SocialAndLocalAccounts/SignUpOrSignIn.xml.

<!--
<RelyingParty> -->
  <Endpoints>
    <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
  </Endpoints>
<!-- 
</RelyingParty> -->

Завершенный элемент проверяющей стороны будет выглядеть так:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TrustFrameworkPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06" PolicySchemaVersion="0.3.0.0" TenantId="yourtenant.onmicrosoft.com" PolicyId="B2C_1A_signup_signin" PublicPolicyUri="http://yourtenant.onmicrosoft.com/B2C_1A_signup_signin">
  <BasePolicy>
    <TenantId>yourtenant.onmicrosoft.com</TenantId>
    <PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>
  </BasePolicy>
  <RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <Endpoints>
      <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
    </Endpoints>
    <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="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>
</TrustFrameworkPolicy>

4. Передача файлов

Войдите на портал Azure.
Если у вас есть доступ к нескольким клиентам, выберите значок Параметры в верхнем меню, чтобы переключиться на клиент Azure AD B2C из меню каталогов и подписок.
Выберите Все службы в левом верхнем углу окна портала Azure, а затем найдите и выберите Azure AD B2C.
Выберите Инфраструктура процедур идентификации.
На странице Настраиваемые политики выберите Отправить настраиваемую политику.
Выберите Перезаписать настраиваемую политику, если она уже существует, а затем найдите и выберите файл TrustframeworkExtensions.xml.
Нажмите кнопку Отправить.
Повторите шаги с 5 по 7 для файла проверяющей стороны, например SignUpOrSignIn.xml.

Вызов конечной точки UserInfo

Конечная точка UserInfo использует стандартный API маркера носителя OAuth2, который вызывается с помощью маркера доступа, полученного вместе с маркером для приложения. Он возвращает ответ JSON, содержащий утверждения о пользователе. Конечная точка UserInfo размещается в Azure AD B2C по адресу:

https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/openid/v2.0/userinfo

Конечная точка /.well-known configure (документ обнаружения OpenID Connect) содержит поле userinfo_endpoint. Конечную точку UserInfo можно программно обнаружить с помощью конечной точки /.well-known configure по адресу:

https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/v2.0/.well-known/openid-configuration

Проверка политики

В разделе Настраиваемые политики выберите политику, которая интегрирована с конечной точкой UserInfo. Например, B2C_1A_SignUpOrSignIn.
Выберите Запустить сейчас.
В разделе Выбор приложения выберите зарегистрированное ранее приложение. В поле Выберите URL-адрес ответа щелкните https://jwt.ms. Дополнительные сведения см. в статье Руководство по регистрации веб-приложения в Azure Active Directory B2C.
Зарегистрируйтесь или войдите с помощью адреса электронной почты или учетной записи социальной сети.
Скопируйте id_token в закодированном формате с веб-сайта https://jwt.ms. Его можно использовать, чтобы отправить запрос GET в конечную точку UserInfo и получить сведения о пользователе.
Отправьте запрос GET в конечную точку UserInfo и получите сведения о пользователе.

GET /yourtenant.onmicrosoft.com/b2c_1a_signup_signin/openid/v2.0/userinfo
Host: b2cninja.b2clogin.com
Authorization: Bearer <your access token>

Успешный ответ выглядит следующим образом:

{
    "objectId": "44444444-4444-4444-4444-444444444444",
    "givenName": "John",
    "surname": "Smith",
    "displayName": "John Smith",
    "signInNames.emailAddress": "john.s@contoso.com"
}

Предоставление необязательных утверждений

Чтобы предоставить приложению больше утверждений, выполните следующие действия.

Добавьте атрибуты пользователя и настройте данные, введенные пользователем.
Измените элемент OutputClaims технического профиля политики проверяющей стороны, добавив утверждения, которые необходимо предоставить. Используйте атрибут DefaultValue, чтобы задать значение по умолчанию. Можно также задать значение по умолчанию для арбитра утверждений, например {Context:CorrelationId}. Чтобы принудительно использовать значение по умолчанию, задайте атрибуту AlwaysUseDefaultValue значение true. В следующем примере добавляется утверждение"city" со значением по умолчанию.
```
<RelyingParty>
  ...
  <TechnicalProfile Id="PolicyProfile">
    ...
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="city" DefaultValue="Berlin" />
    </OutputClaims>
    ...
  </TechnicalProfile>
</RelyingParty>
```
Измените элемент InputClaims технического профиля UserInfoIssuer, добавив утверждения, которые необходимо предоставить. Используйте атрибут PartnerClaimType, чтобы изменить имя утверждения, возвращаемое в приложение. В следующем примере добавляется утверждение"city" и изменяется имя некоторых утверждений.
```
<TechnicalProfile Id="UserInfoIssuer">
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" />
    <InputClaim ClaimTypeReferenceId="city" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="familyName" />
    <InputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
    <InputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
  </InputClaims>
  ...
</TechnicalProfile>
```

Next Steps

Пример политики конечной точки UserInfo можно найти в GitHub.