关于 Azure Active Directory B2C 自定义策略中的声明解析程序

项目
10/14/2024

Azure Active Directory B2C (Azure AD B2C) 自定义策略中的声明解析程序提供关于授权请求的上下文信息，例如策略名称、请求相关 ID、用户界面语言等。

若要在输入或输出声明中使用声明解析程序，请在 ClaimsSchema 元素下定义字符串 ClaimType，然后将 DefaultValue 设置为输入或输出声明元素中的声明解析程序。 Azure AD B2C 读取声明解决程序的值并将该值用于技术配置文件中。

在以下示例中，使用 string 数据类型定义名为 correlationId 的声明类型。

<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。	2052
{Culture:RegionName}	区域的两字母 ISO 代码。	US
{Culture:RFC5646}	RFC5646 语言代码。	zh-CN

查看区域性声明解析程序的实时演示。

策略

下表列出了声明解析程序，以及在授权请求中使用的策略的相关信息：

声明	说明	示例
{Policy:PolicyId}	信赖方策略名称。	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	信赖方策略的租户 ID。	your-tenant.partner.onmschina.cn
{Policy:TenantObjectId}	信赖方策略的租户对象 ID。	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	信任框架的租户 ID。	your-tenant.partner.onmschina.cn

查看策略声明解析程序的实时演示。

上下文

下表列出了授权请求的上下文声明解析程序：

声明	说明	示例
{Context:BuildNumber}	标识体验框架版本（内部版本号）。	1.0.507.0
{Context:CorrelationId}	相关 ID。	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	UTC 格式的日期时间。	2021/10/10 中午 12:00:00
{Context:DeploymentMode}	策略部署模式。	生产
{Context:HostName}	当前请求的主机名。	contoso.b2clogin.cn
{Context:IPAddress}	用户 IP 地址。	11.111.111.11
{Context:KMSI}	指示是否选中了“使我保持登录状态”复选框。	是

查看上下文声明解析程序的实时演示。

声明

此部分介绍如何以声明解析程序的身份获取声明值。

声明	说明	示例
{Claim:claim type}	已在策略文件或父策略文件的 ClaimsSchema 节中定义的声明类型的标识符。例如：`{Claim:displayName}` 或 `{Claim:objectId}`。	声明类型值。

OpenID Connect

下表列出了声明解析程序，以及有关 OpenID Connect 授权请求的信息：

声明	说明	示例
{OIDC:AuthenticationContextReferences}	`acr_values` 查询字符串参数。	空值
{OIDC:ClientId}	`client_id` 查询字符串参数。	00000000-0000-0000-0000-000000000000
{OIDC:DomainHint}	`domain_hint` 查询字符串参数。
{OIDC:LoginHint}	`login_hint` 查询字符串参数。	someone@contoso.com
{OIDC:MaxAge}	`max_age`。	空值
{OIDC:Nonce}	`Nonce` 查询字符串参数。	defaultNonce
{OIDC:Password}	资源所有者密码凭据流用户的密码。	password1
{OIDC:Prompt}	`prompt` 查询字符串参数。	登录
{OIDC:RedirectUri}	`redirect_uri` 查询字符串参数。	https://jwt.ms
{OIDC:Resource}	`resource` 查询字符串参数。	空值
{OIDC:Scope}	`scope` 查询字符串参数。	openid
{OIDC:Username}	资源所有者密码凭据流用户的用户名。	emily@contoso.com
{OIDC:IdToken}	`id token` 查询字符串参数。	空值

查看 OpenID Connect 声明解析程序的实时演示。

OAuth2 键值参数

可以将 OIDC 或 OAuth2 请求中包括的任何参数名称映射到用户旅程中的某个声明，例如，来自应用程序的请求可能包括名为 app_session、loyalty_number 的查询字符串参数或任何自定义查询字符串。

声明	说明	示例
{OAUTH-KV:campaignId}	查询字符串参数。	Hawaii
{OAUTH-KV:app_session}	查询字符串参数。	A3C5R
{OAUTH-KV:loyalty_number}	查询字符串参数。	1234
{OAUTH-KV:any custom query string}	查询字符串参数。	空值

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 正文参数。	空值

SAML

下表列出了声明解析程序，以及有关 SAML 授权请求的信息：

声明	说明	示例
{SAML:AuthnContextClassReferences}	SAML 请求中的 `AuthnContextClassRef` 元素值。	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	SAML 请求的 `NameIDPolicy` 元素中的 `Format` 特性。	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	SAML 请求的 SAML `Issuer` 元素。	`https://contoso.com`
{SAML:AllowCreate}	SAML 请求的 `NameIDPolicy` 元素中的 `AllowCreate` 特性值。	True
{SAML:ForceAuthn}	SAML 请求的 `AuthnRequest` 元素中的 `ForceAuthN` 特性值。	True
{SAML:ProviderName}	SAML 请求的 `AuthnRequest` 元素中的 `ProviderName` 特性值。	Contoso.com
{SAML:RelayState}	`RelayState` 查询字符串参数。
{SAML:Subject}	来自 SAML AuthN 请求的 NameId 元素的 `Subject`。
{SAML:Binding}	SAML 请求的 `AuthnRequest` 元素中的 `ProtocolBinding` 特性值。	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 技术配置文件中，可能想要发送用户语言、策略名称、作用域和客户端 ID。根据这些声明，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.chinacloudsites.cn/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>

使用声明解析程序时，可以预填充登录名或直接登录到特定的社交标识提供者。有关详细信息，请参阅使用 Azure Active Directory B2C 设置直接登录。

动态 UI 自定义

通过 Azue AD B2C，可将查询字符串参数传递给 HTML 内容定义终结点，以便动态呈现页面内容。例如，此功能允许基于从 Web 或移动应用程序传递的自定义参数，更改 Azure AD B2C 注册或登录页面上的背景图像。有关详细信息，请参阅使用 Azure Active Directory B2C 中的自定义策略动态配置 UI。此外，还可以根据语言参数本地化 HTML 页，或者根据客户端 ID 更改内容。

以下示例传入了名为 campaignId 且值为 Hawaii 的查询字符串参数、language 代码 en-US 以及表示客户端 ID 的 app：

<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.chinacloudapi.cn/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Application Insights 技术配置文件

使用 Azure Application Insights 和声明解析程序，可以了解用户行为。在 Application Insights 技术配置文件中，将向 Azure Application Insights 发送保留的输入声明。有关详细信息，请参阅使用 Application Insights 在 Azure AD B2C 过程中跟踪用户行为。下面的示例将向 Azure Application Insights 发送策略 ID、相关 ID、语言 ID 和客户端 ID。

<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 中将租户 ID 或相关 ID 发送给信赖方应用程序。

<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 存储库中查看更多声明解析程序示例

通过