UserInfo 端點

發行項
10/30/2024

開始之前，請使用此頁面頂端的 [選擇原則類型] 選取器，選擇您要設定的原則類型。 Azure Active Directory B2C 提供兩種方法來定義使用者如何與您的應用程式互動：透過預先定義的使用者流程，或透過完全可設定的自訂原則。此文章中所需的步驟隨各方法而異。

UserInfo 端點是 OpenID Connect 標準（OIDC）規格的一部分，其設計目的是傳回已驗證使用者的宣告。 UserInfo 端點是使用 EndPoint 元素在信賴憑證者原則中定義。

此功能僅適用於自訂原則。如需設定步驟，請在前述選取器中選取 [自訂原則]。

必要條件

完成在 Active Directory B2C 中開始使用自訂原則中的步驟。本教學課程會引導您更新自定義原則檔案，以使用您的 Azure AD B2C 租用戶設定。
如果您尚未註冊 Web 應用程式，請使用註冊 Web 應用程式中的步驟來註冊一個 Web 應用程式。

UserInfo 端點概觀

使用者資訊 UserJourney 指定：

授權：UserInfo 端點受到持有人令牌的保護。發出的存取令牌會顯示在UserInfo端點的授權標頭中。原則會指定技術配置檔，以驗證傳入令牌並擷取宣告，例如使用者的 objectId。使用者的 objectId 可用來擷取在 UserInfo 端點旅程圖回應中傳回的宣告。
協調流程步驟：
- 協調流程步驟可用來收集使用者的相關信息。根據傳入存取令牌內的宣告，使用者旅程圖會叫用 Microsoft Entra ID 技術配置檔來擷取使用者的相關數據，例如，依 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/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/</Item>
          <Item Key="audience">[ "00001111-aaaa-2222-bbbb-3333cccc4444", "11112222-bbbb-3333-cccc-4444dddd5555" ]</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.com/your-tenant-id/v2.0/使用簽發者。深入瞭解令牌自定義。
2. IdTokenAudience - 必須與存取令牌宣告內的宣告相同 aud 。在 Azure AD B2C 中， aud 宣告是信賴憑證者應用程式的標識碼。這個值是集合，並支援使用逗號分隔符的多個值。
  
  在下列存取權杖中 iss ，宣告值為 https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/。宣告 aud 值為 00001111-aaaa-2222-bbbb-3333cccc4444。
```
{
  "exp": 1605549468,
  "nbf": 1605545868,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/",
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1605545868,
  "auth_time": 1605545868,
  "name": "John Smith",
  "given_name": "John",
  "family_name": "Smith",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
```
UserInfoAuthorization 技術配置檔的 OutputClaims 元素會指定您要從存取令牌讀取的屬性。 ClaimTypeReferenceId 是宣告類型的參考。選擇性 的 PartnerClaimType 是存取令牌中定義的宣告名稱。

2.新增 UserJourney 元素

UserJourney 元素會定義使用者與應用程式互動時所接受的路徑。 如果 UserJourneys 元素不存在，請將它新增為 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 端點會使用標準 OAuth2 持有人令牌 API，此 API 會使用取得應用程式令牌時收到的存取令牌來呼叫。它會傳回 JSON 回應，其中包含有關使用者的宣告。 UserInfo 端點裝載在 Azure AD B2C 上，位於：

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

/.已知設定端點（OpenID Connect 探索檔）會列出 userinfo_endpoint 字段。您可以使用 /.known configure endpoint at：以程序設計方式探索 UserInfo 端點：

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 中註冊 Web 應用程式。
使用電子郵件位址或社交賬戶註冊或登入。
從 https://jwt.ms 網站複製id_token其編碼格式。您可以使用此選項，將 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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "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 端點原則的範例。

共用方式為