UserInfo 终结点

项目
04/04/2024

开始之前，请使用此页顶部的“选择策略类型”选择器来选择要设置的策略类型。 Azure Active Directory B2C 提供了两种定义用户如何与应用程序交互的方法：通过预定义的用户流，或者通过可完全配置的自定义策略。对于每种方法，本文中所需的步骤都不同。

UserInfo 终结点是 OpenID Connect 标准 (OIDC) 规范的一部分，用于返回有关已通过身份验证的用户的声明。使用 EndPoint 元素在信赖方策略中定义 UserInfo 终结点。

此功能仅适用于自定义策略。对于设置步骤，请在前面的选择器中选择“自定义策略”。

先决条件

完成 Active Directory B2C 中的自定义策略入门中的步骤。本教程指导你如何更新自定义策略文件以使用 Azure AD B2C 租户配置。
如果尚未注册 Web 应用，请按照注册 Web 应用程序中的步骤注册一个。

UserInfo 终结点概述

用户信息 UserJourney 指定：

授权：使用持有者令牌保护 UserInfo 终结点。颁发的访问令牌显示在 UserInfo 终结点的 Authorization 标头中。策略指定用于验证传入令牌并提取声明（例如用户的 objectId）的技术配置文件。用户的 objectId 用于检索在 UserInfo 终结点旅程的响应中返回的声明。
业务流程步骤：
- 业务流程步骤用于收集有关用户的信息。用户旅程会根据传入访问令牌中的声明，调用 Microsoft Entra ID 技术配置文件来检索有关用户的数据，例如按 objectId 读取用户。
- 可选的业务流程步骤 - 可以添加更多的业务流程步骤（例如 REST API 技术配置文件）来检索有关用户的详细信息。
- UserInfo 颁发者 - 指定 UserInfo 终结点返回的声明列表。

创建 UserInfo 终结点

1.添加 Token Issuer 技术配置文件

打开 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.cn/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> -->

UserInfoIssuer 技术配置文件中的 InputClaims 节指定要返回的属性。在用户旅程结束时，会调用 UserInfoIssuer 技术配置文件。
UserInfoAuthorization 技术配置文件会验证签名、颁发者名称和令牌受众，并从入站令牌中提取声明。请更改以下元数据，使之反映你的环境：
1. issuer - 此值必须与访问令牌声明中的 iss 声明相同。 Azure AD B2C 颁发的令牌使用 https://yourtenant.b2clogin.cn/your-tenant-id/v2.0/ 格式的颁发者。详细了解令牌自定义。
2. IdTokenAudience - 必须与访问令牌声明中的 aud 声明相同。在 Azure AD B2C 中，aud 声明是信赖方应用程序的 ID。此值为集合，支持多个使用逗号分隔符的值。
  
  在以下访问令牌中，iss 声明值为 https://contoso.b2clogin.cn/11111111-1111-1111-1111-111111111111/v2.0/。 aud 声明值为 22222222-2222-2222-2222-222222222222。
```
{
  "exp": 1605549468,
  "nbf": 1605545868,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.cn/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"
}
```
UserInfoAuthorization 技术配置文件的 OutputClaims 元素指定要从访问令牌中读取的属性。 ClaimTypeReferenceId 是对声明类型的引用。可选的 PartnerClaimType 是在访问令牌中定义的声明的名称。

2.添加 UserJourney 元素

UserJourney 元素定义用户与应用程序进行交互时使用的路径。如果 UserJourneys 元素不具有标识为 UserInfoJourney 的 UserJourney，则添加一个：

<!-- 
<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.partner.onmschina.cn" PolicyId="B2C_1A_signup_signin" PublicPolicyUri="http://yourtenant.partner.onmschina.cn/B2C_1A_signup_signin">
  <BasePolicy>
    <TenantId>yourtenant.partner.onmschina.cn</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 文件。
单击“上载” 。
针对信赖方文件（例如 SignUpOrSignIn.xml）重复步骤 5 到 7。

调用 UserInfo 终结点

UserInfo 终结点使用标准 OAuth2 持有者令牌 API，该 API 通过使用在获取应用程序令牌时收到的访问令牌来调用。它返回一个 JSON 响应，其中包含有关用户的声明的。 UserInfo 终结点在 Azure AD B2C 上托管，具体位置如下：

https://yourtenant.b2clogin.cn/yourtenant.partner.onmschina.cn/policy-name/openid/v2.0/userinfo

/.well-known 配置终结点（OpenID Connect 发现文档）会列出 userinfo_endpoint 字段。可以使用 /.well-known 配置终结点以编程方式发现 UserInfo 终结点，具体位置如下：

https://yourtenant.b2clogin.cn/yourtenant.partner.onmschina.cn/policy-name/v2.0/.well-known/openid-configuration

测试策略

在“自定义策略”下，选择已将 UserInfo 终结点与之集成的策略。例如，B2C_1A_SignUpOrSignIn。
选择“立即运行”。
在“选择应用程序”下，选择你之前注册的应用程序。对于“选择回复 URL”，请选择 https://jwt.ms。有关详细信息，请参阅在 Azure Active Directory B2C 中注册 Web 应用程序。
使用电子邮件地址或社交帐户注册或登录。
从 https://jwt.ms 网站复制采用编码格式的 id_token。你可以使用此方法向 UserInfo 终结点提交 GET 请求并检索用户信息。
向 UserInfo 终结点提交 GET 请求并检索用户信息。

GET /yourtenant.partner.onmschina.cn/b2c_1a_signup_signin/openid/v2.0/userinfo
Host: b2cninja.b2clogin.cn
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。以下示例使用默认值添加城市声明。
```
<RelyingParty>
  ...
  <TechnicalProfile Id="PolicyProfile">
    ...
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="city" DefaultValue="Berlin" />
    </OutputClaims>
    ...
  </TechnicalProfile>
</RelyingParty>
```

将 UserInfoIssuer 技术配置文件 InputClaims 元素修改为要提供的声明。使用 PartnerClaimType 属性将声明返回的名称更改为应用。以下示例添加了城市声明并更改了一些声明的名称。

<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>

后续步骤

可以在 GitHub 上找到 UserInfo 终结点策略的示例。