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

文章
01/19/2024

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

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

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

<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}	原則部署模式。	實際執行環境
{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 Connect 授權要求的相關信息：

索賠	描述	範例
{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 Connect 宣告解析程式的實時示範。

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>

使用宣告解析程式

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

項目	元素	設定
Application Insights 技術配置檔	`InputClaim`
Microsoft Entra 技術配置檔	`InputClaim`, `OutputClaim`	1, 2
OAuth2 技術配置檔	`InputClaim`, `OutputClaim`	1, 2
OpenID Connect 技術配置檔	`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

設定：

中繼資料 IncludeClaimResolvingInClaimsHandling 必須設定為 true。
輸入或輸出宣告屬性 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

內容定義

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

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

下一步

在 Azure AD B2C 社群 GitHub 存放庫上尋找更多宣告解析程式範例

分享方式：