關於 Azure Active Directory B2C 自定義原則中的宣告解析程式

  • 發行項

Azure Active Directory B2C （Azure AD B2C） 自定義 原則中的宣告解析程式提供授權要求的內容資訊，例如原則名稱、要求相互關聯標識碼、使用者介面語言等等。

若要在輸入或輸出宣告中使用宣告解析程式，您可以在 ClaimsSchema 元素下定義字串 ClaimType，然後將 DefaultValue 設定為輸入或輸出宣告元素中的宣告解析程式。 Azure AD B2C 會讀取宣告解析程式的值，並使用技術配置檔中的值。

在下列範例中，名為 correlationId 的宣告類型是以的 DataTypestring定義。

<ClaimType Id="correlationId">
  <DisplayName>correlationId</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Request correlation Id</UserHelpText>
</ClaimType>

在技術配置檔中，將宣告解析程式對應至宣告類型。 Azure AD B2C 會將宣告解析程式 {Context:CorrelationId} 的值填入宣告 correlationId ，並將宣告傳送至技術配置檔。

<InputClaim ClaimTypeReferenceId="correlationId" DefaultValue="{Context:CorrelationId}" />

文化特性

下表列出宣告解析程式，其中包含授權要求中使用的語言相關信息：

索賠 描述 範例
{Culture：LanguageName} 語言的兩個字母 ISO 代碼。 en
{Culture：LCID} 語言代碼的 LCID。 1033
{Culture：RegionName} 區域的兩個字母 ISO 代碼。 美國
{Culture：RFC5646} RFC5646語言代碼。 zh-TW

查看 文化宣告解析程式的實時示範 。

原則

下表列出宣告解析程式，其中包含授權要求中使用的原則相關信息：

索賠 描述 範例
{Policy：PolicyId} 信賴憑證者原則名稱。 B2C_1A_signup_signin
{Policy：RelyingPartyTenantId} 信賴憑證者原則的租用戶標識符。 your-tenant.onmicrosoft.com
{Policy：TenantObjectId} 信賴憑證者原則的租用戶物件標識符。 00000000-0000-0000-0000-000000000000
{Policy：TrustFrameworkTenantId} 信任架構的租用戶標識碼。 your-tenant.onmicrosoft.com

查看 原則宣告解析程式的實時示範 。

上下文

下表列出授權要求的內容宣告解析程式：

索賠 描述 範例
{Context：BuildNumber} 身分識別體驗架構版本（組建編號）。 1.0.507.0
{Context：CorrelationId} 相互關聯標識碼。 00000000-0000-0000-0000-000000000000
{Context：DateTimeInUtc} UTC 的日期時間。 2021/10/10 下午 12：00：00
{Context：DeploymentMode} 原則部署模式。 Production
{Context：HostName} 目前要求的主機名。 contoso.b2clogin.com
{Context：IPAddress} 使用者IP位址。 11.111.111.11
{Context：KMSI} 指出是否已選取 [ 讓我保持登入 ] 複選框。 true

查看 內容宣告解析程式的實時示範 。

宣告

本節說明如何取得宣告值作為宣告解析程式。

索賠 描述 範例
{Claim：claim type} 已在原則檔或父原則檔案之 ClaimsSchema 區段中定義的宣告類型識別碼。 例如： {Claim:displayName}、 或 {Claim:objectId}。 宣告類型值。

OpenID Connect

下表列出宣告解析程式，其中包含 OpenID 連線 授權要求的相關信息：

索賠 描述 範例
{OIDC：AuthenticationContextReferences} acr_values查詢字串參數。 N/A
{OIDC：ClientId} client_id查詢字串參數。 00000000-0000-0000-0000-000000000000
{OIDC：DomainHint} domain_hint查詢字串參數。 facebook.com
{OIDC：LoginHint} login_hint查詢字串參數。 someone@contoso.com
{OIDC：MaxAge} max_age。 N/A
{OIDC：Nonce} Nonce查詢字串參數。 defaultNonce
{OIDC：Password} 資源 擁有者密碼認證流程 用戶的密碼。 password1
{OIDC：Prompt} prompt查詢字串參數。 login
{OIDC：RedirectUri} redirect_uri查詢字串參數。 https://jwt.ms
{OIDC：Resource} resource查詢字串參數。 N/A
{OIDC：Scope} scope查詢字串參數。 openid
{OIDC：Username} 資源 擁有者密碼認證流程 使用者的用戶名稱。 emily@contoso.com
{OIDC：IdToken} id token查詢字串參數。 N/A

查看 OpenID 連線 宣告解析程式的實時示範。

OAuth2 機碼/值參數

包含在 OIDC 或 OAuth2 要求中的任何參數名稱，都可以對應至使用者旅程圖中的宣告。 例如，來自應用程式的要求可能包含名稱為、 loyalty_number或任何自定義查詢字串的app_session查詢字元串參數。

索賠 描述 範例
{OAUTH-KV：campaignId} 查詢字串參數。 夏威夷州
{OAUTH-KV：app_session} 查詢字串參數。 A3C5R
{OAUTH-KV：loyalty_number} 查詢字串參數。 1234
{OAUTH-KV：any custom query string} 查詢字串參數。 N/A

SAML 索引鍵/值參數

在 SAML 驗證要求中，要求中包含的任何參數名稱，但並非特定通訊協定（例如 SAMLRequest）可以對應至使用者旅程圖中的宣告。 例如，要求可能包含自訂參數，例如 username。 這同時適用於SP起始和IDP起始的SAML要求。

索賠 描述 範例
{SAML-KV：username} 查詢字串或 POST 主體參數。 username@domain.com
{SAML-KV：loyalty_number} 查詢字串或 POST 主體參數。 1234
{SAML-KV：any custom query string} 查詢字串或 POST 主體參數。 N/A

SAML

下表列出宣告解析程式，其中包含SAML授權要求的相關信息：

索賠 描述 範例
{SAML：AuthnContextClassReferences} AuthnContextClassRef SAML 要求中的專案值。 urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML：NameIdPolicyFormat} Format屬性，來自 NameIDPolicy SAML 要求的 元素。 urn：oasis：names：tc：SAML：1.1：nameid-format：emailAddress
{SAML：Issuer} SAML 要求的 SAML Issuer 元素值。 https://contoso.com
{SAML：AllowCreate} AllowCreate來自 SAML 要求的 元素的屬性值NameIDPolicy。 True
{SAML：ForceAuthn} ForceAuthN來自 SAML 要求的 元素的屬性值AuthnRequest。 True
{SAML：ProviderName} ProviderName來自 SAML 要求的 元素的屬性值AuthnRequest。 Contoso.com
{SAML：RelayState} RelayState查詢字串參數。
{SAML：Subject} Subject從 SAML AuthN 要求的 NameId 元素的 。
{SAML：Binding} ProtocolBinding來自 SAML 要求的 元素的屬性值AuthnRequest。 urn：oasis：names：tc：SAML：2.0：bindings：HTTP-POST

查看 SAML 宣告解析程式的實時示範 。

OAuth2 識別提供者

下表列出 OAuth2 識別提供者 宣告解析程式：

索賠 描述 範例
{oauth2：access_token} OAuth2 識別提供者存取令牌。 access_token 屬性。 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...
{oauth2：token_type} 存取令牌的類型。 token_type 屬性。 承載
{oauth2：expires_in} 存取令牌在秒內有效的時間長度。 expires_in 屬性。 輸出宣告 DataType 必須是 int 或 long。 960000
{oauth2：refresh_token} OAuth2 識別提供者重新整理令牌。 refresh_token 屬性。 eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...

若要使用 OAuth2 識別提供者宣告解析程式，請將輸出宣告的 PartnerClaimType 屬性設定為宣告解析程式。 下列範例示範如何取得外部識別提供者宣告：

<ClaimsProvider>
  <DisplayName>Contoso</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Contoso-OAUTH">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessToken" PartnerClaimType="{oauth2:access_token}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenType" PartnerClaimType="{oauth2:token_type}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenExpiresIn" PartnerClaimType="{oauth2:expires_in}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="{oauth2:refresh_token}" />
      </OutputClaims>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

使用宣告解析程式

您可以使用宣告解析程式搭配下列元素：

項目 Element 設定
Application Insights 技術配置檔 InputClaim
Microsoft Entra 技術配置檔 InputClaim, OutputClaim 1, 2
OAuth2 技術配置檔 InputClaim, OutputClaim 1, 2
OpenID 連線 技術配置檔 InputClaim, OutputClaim 1, 2
宣告轉換 技術配置檔 InputClaim, OutputClaim 1, 2
RESTful 提供者 技術配置檔 InputClaim 1, 2
SAML 識別提供者 技術配置檔 OutputClaim 1, 2
自我判斷 技術配置檔 InputClaim, OutputClaim 1, 2
ContentDefinition LoadUri
ContentDefinitionParameters Parameter
RelyingParty 技術配置檔 OutputClaim 2

設定：

  1. 中繼資料 IncludeClaimResolvingInClaimsHandling 必須設定為 true。
  2. 輸入或輸出宣告屬性 AlwaysUseDefaultValue 必須設定為 true。

宣告解析程式範例

RESTful 技術配置檔

在 RESTful 技術設定檔中，您可能會想要傳送使用者語言、原則名稱、範圍和用戶端識別碼。 根據宣告，REST API 可以執行自定義商業規則，並在必要時引發本地化的錯誤訊息。

下列範例示範此案例的 RESTful 技術配置檔：

<TechnicalProfile Id="REST">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="policyName" DefaultValue="{Policy:PolicyId}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="scope" DefaultValue="{OIDC:Scope}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="clientId" DefaultValue="{OIDC:ClientId}" AlwaysUseDefaultValue="true" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

直接登入

使用宣告解析程式，您可以預先填入登入名稱或直接登入特定社交識別提供者，例如 Facebook、LinkedIn或 Microsoft 帳戶。 如需詳細資訊，請參閱 使用 Azure Active Directory B2C 設定直接登入。

動態UI自定義

Azure AD B2C 可讓您將查詢字串參數傳遞至 HTML 內容定義端點，以動態呈現頁面內容。 例如，這項功能可讓您根據您從 Web 或行動應用程式傳遞的自定義參數，修改 Azure AD B2C 註冊或登入頁面上的背景影像。 如需詳細資訊，請參閱 在 Azure Active Directory B2C 中使用自定義原則動態設定 UI。 您也可以根據語言參數將 HTML 頁面當地語系化，也可以根據用戶端識別碼變更內容。

下列範例會傳入名為 campaignId 的查詢字串參數，其值為 Hawaii、語言代碼en-US，以及代表用戶端識別符的應用程式：

<UserJourneyBehaviors>
  <ContentDefinitionParameters>
    <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
    <Parameter Name="language">{Culture:RFC5646}</Parameter>
    <Parameter Name="app">{OIDC:ClientId}</Parameter>
  </ContentDefinitionParameters>
</UserJourneyBehaviors>

因此，Azure AD B2C 會將上述參數傳送至 HTML 內容頁面：

/selfAsserted.aspx?campaignId=hawaii&language=en-US&app=0239a9cc-309c-4d41-87f1-31288feb2e82

內容定義

在 ContentDefinitionLoadUri 中，您可以根據所使用的參數，傳送宣告解析程式從不同位置提取內容。

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://contoso.blob.core.windows.net/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Application Insights 技術配置檔

透過 Azure 應用程式 Insights 和宣告解析程式，您可以深入瞭解用戶行為。 在 Application Insights 技術設定檔中，您會傳送保存至 Azure 應用程式 Insights 的輸入宣告。 如需詳細資訊，請參閱 使用 Application Insights 追蹤 Azure AD B2C 旅程圖中的用戶行為。 下列範例會將原則標識碼、相互關聯標識符、語言和用戶端標識碼傳送至 Azure 應用程式 Insights。

<TechnicalProfile Id="AzureInsights-Common">
  <DisplayName>Alternate Email</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.Insights.AzureApplicationInsightsProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="PolicyId" PartnerClaimType="{property:Policy}" DefaultValue="{Policy:PolicyId}" />
    <InputClaim ClaimTypeReferenceId="CorrelationId" PartnerClaimType="{property:CorrelationId}" DefaultValue="{Context:CorrelationId}" />
    <InputClaim ClaimTypeReferenceId="language" PartnerClaimType="{property:language}" DefaultValue="{Culture:RFC5646}" />
    <InputClaim ClaimTypeReferenceId="AppId" PartnerClaimType="{property:App}" DefaultValue="{OIDC:ClientId}" />
  </InputClaims>
</TechnicalProfile>

信賴憑證者原則

在信賴憑證者原則技術配置檔中，您可能會想要將租使用者標識碼或相互關聯標識碼傳送至 JWT 內的信賴憑證者應用程式。

<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="correlationId" AlwaysUseDefaultValue="true" DefaultValue="{Context:CorrelationId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>

下一步