关于 Azure Active Directory B2C 自定义策略中的声明解析程序About claim resolvers in Azure Active Directory B2C custom policies

Azure Active Directory B2C (Azure AD B2C) 自定义策略中的声明解析程序提供关于授权请求的上下文信息,例如策略名称、请求相关 ID、用户界面语言等。Claim resolvers in Azure Active Directory B2C (Azure AD B2C) custom policies provide context information about an authorization request, such as the policy name, request correlation ID, user interface language, and more.

若要在输入或输出声明中使用声明解析程序,请在 ClaimsSchema 元素下定义字符串 ClaimType,然后将 DefaultValue 设置为输入或输出声明元素中的声明解析程序 。To use a claim resolver in an input or output claim, you define a string ClaimType, under the ClaimsSchema element, and then you set the DefaultValue to the claim resolver in the input or output claim element. Azure AD B2C 读取声明解决程序的值并将该值用于技术配置文件中。Azure AD B2C reads the value of the claim resolver and uses the value in the technical profile.

在以下示例中,使用 string 数据类型定义名为 correlationId 的声明类型。In the following example, a claim type named correlationId is defined with a DataType of string.

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

在技术配置文件中,将声明解析程序映射到声明类型。In the technical profile, map the claim resolver to the claim type. Azure AD B2C 将声明解析程序的值 {Context:CorrelationId} 填充到声明 correlationId 中,并向技术配置文件发送声明。Azure AD B2C populates the value of the claim resolver {Context:CorrelationId} into the claim correlationId and sends the claim to the technical profile.

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

声明解析程序类型Claim resolver types

以下部分列出了可用的声明解析程序。The following sections list available claim resolvers.

环境Culture

声明Claim 说明Description 示例Example
{Culture:LanguageName}{Culture:LanguageName} 语言的两字母 ISO 代码。The two letter ISO code for the language. enen
{Culture:LCID}{Culture:LCID} 语言代码的 LCID。The LCID of language code. 20521033
{Culture:RegionName}{Culture:RegionName} 区域的两字母 ISO 代码。The two letter ISO code for the region. USUS
{Culture:RFC5646}{Culture:RFC5646} RFC5646 语言代码。The RFC5646 language code. zh-CNen-US

策略Policy

声明Claim 说明Description 示例Example
{Policy:PolicyId}{Policy:PolicyId} 信赖方策略名称。The relying party policy name. B2C_1A_signup_signinB2C_1A_signup_signin
{Policy:RelyingPartyTenantId}{Policy:RelyingPartyTenantId} 信赖方策略的租户 ID。The tenant ID of the relying party policy. your-tenant.partner.onmschina.cnyour-tenant.partner.onmschina.cn
{Policy:TenantObjectId}{Policy:TenantObjectId} 信赖方策略的租户对象 ID。The tenant object ID of the relying party policy. 00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}{Policy:TrustFrameworkTenantId} 信任框架的租户 ID。The tenant ID of the trust framework. your-tenant.partner.onmschina.cnyour-tenant.partner.onmschina.cn

OpenID ConnectOpenID Connect

声明Claim 说明Description 示例Example
{OIDC:AuthenticationContextReferences}{OIDC:AuthenticationContextReferences} acr_values 查询字符串参数。The acr_values query string parameter. 空值N/A
{OIDC:ClientId}{OIDC:ClientId} client_id 查询字符串参数。The client_id query string parameter. 00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000
{OIDC:DomainHint}{OIDC:DomainHint} domain_hint 查询字符串参数。The domain_hint query string parameter.
{OIDC:LoginHint}{OIDC:LoginHint} login_hint 查询字符串参数。The login_hint query string parameter. someone@contoso.com
{OIDC:MaxAge}{OIDC:MaxAge} max_ageThe max_age. 空值N/A
{OIDC:Nonce}{OIDC:Nonce} Nonce 查询字符串参数。The Nonce query string parameter. defaultNoncedefaultNonce
{OIDC:Password}{OIDC:Password} 资源所有者密码凭据流用户的密码。The resource owner password credentials flow user's password. password1password1
{OIDC:Prompt}{OIDC:Prompt} prompt 查询字符串参数。The prompt query string parameter. 登录login
{OIDC:RedirectUri}{OIDC:RedirectUri} redirect_uri 查询字符串参数。The redirect_uri query string parameter. https://jwt.ms
{OIDC:Resource}{OIDC:Resource} resource 查询字符串参数。The resource query string parameter. 空值N/A
{OIDC:Scope}{OIDC:Scope} scope 查询字符串参数。The scope query string parameter. openidopenid
{OIDC:Username}{OIDC:Username} 资源所有者密码凭据流用户的用户名。The resource owner password credentials flow user's username. emily@contoso.com

上下文Context

声明Claim 说明Description 示例Example
{Context:BuildNumber}{Context:BuildNumber} 标识体验框架版本(内部版本号)。The Identity Experience Framework version (build number). 1.0.507.01.0.507.0
{Context:CorrelationId}{Context:CorrelationId} 相关 ID。The correlation ID. 00000000-0000-0000-0000-00000000000000000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}{Context:DateTimeInUtc} UTC 格式的日期时间。The date time in UTC. 2018/10/10 中午 12:0010/10/2018 12:00:00 PM
{Context:DeploymentMode}{Context:DeploymentMode} 策略部署模式。The policy deployment mode. 生产Production
{Context:IPAddress}{Context:IPAddress} 用户 IP 地址。The user IP address. 11.111.111.1111.111.111.11
{Context:KMSI}{Context:KMSI} 指示是否选中 Keep me signed in 复选框。Indicates whether Keep me signed in checkbox is selected. true

声明Claims

声明Claim 说明Description 示例Example
{Claim:claim type}{Claim:claim type} 已在策略文件或父策略文件的 ClaimsSchema 节中定义的声明类型的标识符。An identifier of a claim type already defined in the ClaimsSchema section in the policy file or parent policy file. 例如:{Claim:displayName}{Claim:objectId}For example: {Claim:displayName}, or {Claim:objectId}. 声明类型值。A claim type value.

OAuth2 键值参数OAuth2 key-value parameters

可以将 OIDC 或 OAuth2 请求中包括的任何参数名称映射到用户旅程中的某个声明,Any parameter name included as part of an OIDC or OAuth2 request can be mapped to a claim in the user journey. 例如,来自应用程序的请求可能包括名为 app_sessionloyalty_number 的查询字符串参数或任何自定义查询字符串。For example, the request from the application might include a query string parameter with a name of app_session, loyalty_number, or any custom query string.

声明Claim 说明Description 示例Example
{OAUTH-KV:campaignId}{OAUTH-KV:campaignId} 查询字符串参数。A query string parameter. HawaiiHawaii
{OAUTH-KV:app_session}{OAUTH-KV:app_session} 查询字符串参数。A query string parameter. A3C5RA3C5R
{OAUTH-KV:loyalty_number}{OAUTH-KV:loyalty_number} 查询字符串参数。A query string parameter. 12341234
{OAUTH-KV:any custom query string}{OAUTH-KV:any custom query string} 查询字符串参数。A query string parameter. 空值N/A

OAuth2OAuth2

声明Claim 说明Description 示例Example
{oauth2:access_token}{oauth2:access_token} 访问令牌。The access token. 空值N/A

SAMLSAML

声明Claim 说明Description 示例Example
{SAML:AuthnContextClassReferences}{SAML:AuthnContextClassReferences} SAML 请求中的 AuthnContextClassRef 元素值。The AuthnContextClassRef element value, from the SAML request. urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransporturn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}{SAML:NameIdPolicyFormat} SAML 请求的 NameIDPolicy 元素中的 Format 特性。The Format attribute, from the NameIDPolicy element of the SAML request. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressurn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}{SAML:Issuer} SAML 请求的 SAML Issuer 元素。The SAML Issuer element value of the SAML request. https://contoso.com
{SAML:AllowCreate}{SAML:AllowCreate} SAML 请求的 NameIDPolicy 元素中的 AllowCreate 特性值。The AllowCreate attribute value, from the NameIDPolicy element of the SAML request. TrueTrue
{SAML:ForceAuthn}{SAML:ForceAuthn} SAML 请求的 AuthnRequest 元素中的 ForceAuthN 特性值。The ForceAuthN attribute value, from the AuthnRequest element of the SAML request. TrueTrue
{SAML:ProviderName}{SAML:ProviderName} SAML 请求的 AuthnRequest 元素中的 ProviderName 特性值。The ProviderName attribute value, from the AuthnRequest element of the SAML request. Contoso.comContoso.com
{SAML:RelayState}{SAML:RelayState} RelayState 查询字符串参数。The RelayState query string parameter.

使用声明解析程序Using claim resolvers

可以将声明解析程序用于以下元素:You can use claims resolvers with the following elements:

项目Item 元素Element 设置Settings
Application Insights 技术配置文件Application Insights technical profile InputClaim
Azure Active Directory 技术配置文件Azure Active Directory technical profile InputClaim, OutputClaimInputClaim, OutputClaim 1, 21, 2
OAuth2 技术配置文件OAuth2 technical profile InputClaim, OutputClaimInputClaim, OutputClaim 1, 21, 2
OpenID Connect 技术配置文件OpenID Connect technical profile InputClaim, OutputClaimInputClaim, OutputClaim 1, 21, 2
声明转换技术配置文件Claims transformation technical profile InputClaim, OutputClaimInputClaim, OutputClaim 1, 21, 2
RESTful 提供程序技术配置文件RESTful provider technical profile InputClaim 1, 21, 2
SAML 标识提供程序技术配置文件SAML identity provider technical profile OutputClaim 1, 21, 2
自断言技术配置文件Self-Asserted technical profile InputClaim, OutputClaimInputClaim, OutputClaim 1, 21, 2
ContentDefinitionContentDefinition LoadUri
ContentDefinitionParametersContentDefinitionParameters Parameter
RelyingParty 技术配置文件RelyingParty technical profile OutputClaim 22

设置:Settings:

  1. IncludeClaimResolvingInClaimsHandling 元数据必须设置为 trueThe IncludeClaimResolvingInClaimsHandling metadata must be set to true.
  2. 输入或输出声明属性 AlwaysUseDefaultValue 必须设置为 trueThe input or output claims attribute AlwaysUseDefaultValue must be set to true.

声明解析程序示例Claim resolvers samples

RESTful 技术配置文件RESTful technical profile

RESTful 技术配置文件中,可能想要发送用户语言、策略名称、作用域和客户端 ID。In a RESTful technical profile, you may want to send the user language, policy name, scope, and client ID. 根据这些声明,REST API 可以运行自定义业务逻辑,并引发已本地化的错误消息(如有必要)。Based on the claims the REST API can run custom business logic, and if necessary raise a localized error message.

以下示例演示了具有此方案的一个 RESTful 技术配置文件:The following example shows a RESTful technical profile with this scenario:

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

直接登录Direct sign-in

使用声明解析程序时,可以预填充登录名或直接登录到特定的社交标识提供者,例如 LinkedIn。Using claim resolvers, you can prepopulate the sign-in name or direct sign-in to a specific social identity provider, such as LinkedIn. 有关详细信息,请参阅使用 Azure Active Directory B2C 设置直接登录For more information, see Set up direct sign-in using Azure Active Directory B2C.

动态 UI 自定义Dynamic UI customization

通过 Azue AD B2C,可将查询字符串参数传递给 HTML 内容定义终结点,以便动态呈现页面内容。Azure AD B2C enables you to pass query string parameters to your HTML content definition endpoints to dynamically render the page content. 例如,此功能允许基于从 Web 或移动应用程序传递的自定义参数,更改 Azure AD B2C 注册或登录页面上的背景图像。For example, this feature allows the ability to modify the background image on the Azure AD B2C sign-up or sign-in page based on a custom parameter that you pass from your web or mobile application. 此外,还可以根据语言参数本地化 HTML 页,或者根据客户端 ID 更改内容。You can also localize your HTML page based on a language parameter, or you can change the content based on the client ID.

以下示例传入了名为 campaignId 且值为 Hawaii 的查询字符串参数、language 代码 en-US 以及表示客户端 ID 的 appThe following example passes in the query string parameter named campaignId with a value of Hawaii, a language code of en-US, and app representing the client ID:

<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 内容页:As a result, Azure AD B2C sends the above parameters to the HTML content page:

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

内容定义Content definition

ContentDefinition LoadUri 中,可以发送声明解析程序来根据所使用的参数从不同的位置拉取内容。In a ContentDefinition LoadUri, you can send claim resolvers to pull content from different places, based on the parameters used.

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

Application Insights 技术配置文件Application Insights technical profile

使用 Azure Application Insights 和声明解析程序,可以了解用户行为。With Azure Application Insights and claim resolvers you can gain insights on user behavior. 在 Application Insights 技术配置文件中,将向 Azure Application Insights 发送保留的输入声明。In the Application Insights technical profile, you send input claims that are persisted to Azure Application Insights. 下面的示例将向 Azure Application Insights 发送策略 ID、相关 ID、语言 ID 和客户端 ID。The following example sends the policy ID, correlation ID, language, and the client ID to Azure Application 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>

信赖方策略Relying party policy

信赖方策略技术配置文件中,你可能希望在 JWT 中将租户 ID 或相关 ID 发送给信赖方应用程序。In a Relying party policy technical profile, you may want to send the tenant ID, or correlation ID to the relying party application within the 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>