定义采用 Azure Active Directory B2C 中自定义策略的自断言技术配置文件Define a self-asserted technical profile in an Azure Active Directory B2C custom policy

备注

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. 大多数情况下,建议使用内置的用户流For most scenarios, we recommend that you use built-in user flows.

在 Azure Active Directory B2C (Azure AD B2C) 中用户需要提供输入的所有交互都属于自我断言技术配置文件。All interactions in Azure Active Directory B2C (Azure AD B2C) where the user is expected to provide input are self-asserted technical profiles. 例如,注册页面、登录页面或密码重置页面。For example, a sign-up page, sign-in page, or password reset page.

协议Protocol

“Protocol”元素的“Name”属性必须设置为 ProprietaryThe Name attribute of the Protocol element needs to be set to Proprietary. “handler” 属性必须包含 Azure AD B2C 用来自断言的协议处理程序程序集的完全限定名称:Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=nullThe handler attribute must contain the fully qualified name of the protocol handler assembly that is used by Azure AD B2C, for self-asserted: Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

下面的示例显示了电子邮件注册的自断言技术配置文件:The following example shows a self-asserted technical profile for email sign-up:

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

输入声明Input claims

在自断言技术配置文件中,你可以使用“InputClaims”和“InputClaimsTransformations”元素预填充自断言页面上出现的声明的值(显示声明) 。In a self-asserted technical profile, you can use the InputClaims and InputClaimsTransformations elements to prepopulate the value of the claims that appear on the self-asserted page (display claims). 例如,在编辑配置文件策略中,用户旅程首先从 Azure AD B2C 目录服务读取用户配置文件,然后自断言技术配置文件使用用户配置文件中存储的用户数据设置输入声明。For example, in the edit profile policy, the user journey first reads the user profile from the Azure AD B2C directory service, then the self-asserted technical profile sets the input claims with the user data stored in the user profile. 这些声明是从用户配置文件中收集的,然后呈现给可以编辑现有数据的用户。These claims are collected from the user profile and then presented to the user who can then edit the existing data.

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" />
  </InputClaims>

显示声明Display claims

此显示声明功能目前以预览版提供 。The display claims feature is currently in preview.

“DisplayClaims”元素包含要呈现在屏幕上用于从用户处收集数据的声明列表 。The DisplayClaims element contains a list of claims to be presented on the screen for collecting data from the user. 若要预填充显示声明的值,请使用前面介绍的输入声明。To prepopulate the values of display claims, use the input claims that were previously described. 另外,此元素还可能包含默认值。The element may also contain a default value.

“DisplayClaims”中的声明顺序指定 Azure AD B2C 在屏幕上呈现声明的顺序 。The order of the claims in DisplayClaims specifies the order in which Azure AD B2C renders the claims on the screen. 若要强制用户提供特定声明的值,请将“DisplayClaim”元素的“Required”属性设置为 trueTo force the user to provide a value for a specific claim, set the Required attribute of the DisplayClaim element to true.

“DisplayClaims”集合中的“ClaimType”元素需要将“UserInputType”元素设置为 Azure AD B2C 支持的任意用户输入类型 。The ClaimType element in the DisplayClaims collection needs to set the UserInputType element to any user input type supported by Azure AD B2C. 例如,TextBoxDropdownSingleSelectFor example, TextBox or DropdownSingleSelect.

添加对 DisplayControl 的引用Add a reference to a DisplayControl

在显示声明集合中,可以包含对已创建的 DisplayControl 的引用。In the display claims collection, you can include a reference to a DisplayControl that you've created. 显示控件是一个具有特殊功能的用户界面元素,可以与 Azure AD B2C 后端服务进行交互。A display control is a user interface element that has special functionality and interacts with the Azure AD B2C back-end service. 它允许用户在页面上执行某些操作,这些操作在后端调用验证技术配置文件。It allows the user to perform actions on the page that invoke a validation technical profile at the back end. 例如,验证电子邮件地址、电话号码或客户会员号。For example, verifying an email address, phone number, or customer loyalty number.

以下示例 TechnicalProfile 阐释了如何配合使用显示声明和显示控件。The following example TechnicalProfile illustrates the use of display claims with display controls.

  • 第一个显示声明引用收集和验证电子邮件地址的 emailVerificationControl 显示控件。The first display claim makes a reference to the emailVerificationControl display control, which collects and verifies the email address.
  • 第五个显示声明引用收集和验证电话号码的 phoneVerificationControl 显示控件。The fifth display claim makes a reference to the phoneVerificationControl display control, which collects and verifies a phone number.
  • 其他显示声明为 ClaimTypes,要从用户处收集。The other display claims are ClaimTypes to be collected from the user.
<TechnicalProfile Id="Id">
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim DisplayControlReferenceId="phoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
</TechnicalProfile>

如上所述,引用显示控件的显示声明可以自己运行验证,例如,验证电子邮件地址。As mentioned, a display claim with a reference to a display control may run its own validation, for example verifying the email address. 此外,自断言页面支持在执行下一个业务流程步骤之前使用验证技术配置文件来验证整个页面,包括任何用户输入(声明类型或显示控件)。In addition, the self-asserted page supports using a validation technical profile to validate the entire page, including any user input (claim types or display controls), before moving on to the next orchestration step.

谨慎细心地配合使用显示声明和输出声明Combine usage of display claims and output claims carefully

如果在自断言技术配置文件中指定一个或多个“DisplayClaim”元素,则必须对要从用户处收集的、要在屏幕上显示的每个声明使用 DisplayClaim 。If you specify one or more DisplayClaim elements in a self-asserted technical profile, you must use a DisplayClaim for every claim that you want to display on-screen and collect from the user. 至少包含一个显示声明的自断言技术配置文件中不显示任何输出声明。No output claims are displayed by a self-asserted technical profile that contains at least one display claim.

请思考以下示例,其中 age 声明被定义为基本策略中的输出声明 。Consider the following example in which an age claim is defined as an output claim in a base policy. 在将任何显示声明添加到自断言技术配置文件之前,屏幕上会显示 age 声明,用于从用户处收集数据:Before adding any display claims to the self-asserted technical profile, the age claim is displayed on the screen for data collection from the user:

<TechnicalProfile Id="id">
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="age" />
  </OutputClaims>
</TechnicalProfile>

如果继承了该基本策略的叶策略随后指定 officeNumber 作为显示声明 :If a leaf policy that inherits that base subsequently specifies officeNumber as a display claim:

<TechnicalProfile Id="id">
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="officeNumber" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="officeNumber" />
  </OutputClaims>
</TechnicalProfile>

屏幕上不再向用户显示基本策略中的 age 声明 - 它实际上处于“隐藏”状态。The age claim in the base policy is no longer presented on the screen to the user - it's effectively "hidden." 若要显示 age 声明并从用户处收集“年龄”值,需要将 age 添加到 DisplayClaim 。To display the age claim and collect the age value from the user, you must add an age DisplayClaim.

输出声明Output claims

“OutputClaims”元素包含要返回到下一个业务流程步骤的的声明列表 。The OutputClaims element contains a list of claims to be returned to the next orchestration step. “DefaultValue”属性只有在从未设置过声明的情况下才会生效 。The DefaultValue attribute takes effect only if the claim has never been set. 如果在上一业务流程步骤中设置过,即使用户将值留空,默认值也不会生效。If it was set in a previous orchestration step, the default value does not take effect even if the user leaves the value empty. 若要强制使用默认值,请将“AlwaysUseDefaultValue” 属性设置为 trueTo force the use of a default value, set the AlwaysUseDefaultValue attribute to true.

出于安全原因,密码声明值(UserInputType 设置为 Password)仅可用于自断言技术配置文件的验证技术配置文件。For security reasons, a password claim value (UserInputType set to Password) is available only to the self-asserted technical profile's validation technical profiles. 在下一个业务流程步骤中,不能使用密码声明。You cannot use password claim in the next orchestration steps.

备注

在以前的 Identity Experience Framework (IEF) 版本中,输出声明用于从用户处收集数据。In previous versions of the Identity Experience Framework (IEF), output claims were used to collect data from the user. 若要从用户处收集数据,请改用“DisplayClaims”集合 。To collect data from the user, use a DisplayClaims collection instead.

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

何时应使用输出声明When you should use output claims

在自断言技术配置文件中,输出声明集合将声明返回到下一个业务流程步骤。In a self-asserted technical profile, the output claims collection returns the claims to the next orchestration step.

在以下情况下使用输出声明:Use output claims when:

  • 声明由输出声明转换输出 。Claims are output by output claims transformation.
  • 在输出声明中设置默认值无需从用户处收集数据或从验证技术配置文件返回数据 。Setting a default value in an output claim without collecting data from the user or returning the data from the validation technical profile. LocalAccountSignUpWithLogonEmail 自断言技术配置文件将“executed-SelfAsserted-Input” 声明设置为 trueThe LocalAccountSignUpWithLogonEmail self-asserted technical profile sets the executed-SelfAsserted-Input claim to true.
  • 验证技术配置文件返回输出声明 - 你的技术配置文件可以调用返回某些声明的验证技术配置文件。A validation technical profile returns the output claims - Your technical profile may call a validation technical profile that returns some claims. 你需要发出声明并将其返回到用户旅程中的下一个业务流程步骤。You may want to bubble up the claims and return them to the next orchestration steps in the user journey. 例如,当使用本地帐户登录时,名为 SelfAsserted-LocalAccountSignin-Email 的自断言技术配置文件会调用名为 login-NonInteractive 的验证技术配置文件。For example, when signing in with a local account, the self-asserted technical profile named SelfAsserted-LocalAccountSignin-Email calls the validation technical profile named login-NonInteractive. 此技术配置文件将验证用户凭据,并返回用户配置文件。This technical profile validates the user credentials and also returns the user profile. 例如“userPrincipalName”、“displayName”、“givenName”和“surName”。Such as 'userPrincipalName', 'displayName', 'givenName' and 'surName'.
  • 显示控件返回输出声明 - 技术配置文件可能引用显示控件A display control returns the output claims - Your technical profile may have a reference to a display control. 显示控件返回某些声明,如已验证的电子邮件地址。The display control returns some claims, such as the verified email address. 你需要发出声明并将其返回到用户旅程中的下一个业务流程步骤。You may want to bubble up the claims and return them to the next orchestration steps in the user journey. 此显示控件功能目前以预览版提供 。The display control feature is currently in preview.

以下示例演示如何使用同时包含显示声明和输出声明的自断言技术配置文件。The following example demonstrates the use of a self-asserted technical profile that uses both display claims and output claims.

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="IpAddressClaimReferenceId">IpAddress</Item>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    <Item Key="language.button_continue">Create</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="email" />
  </InputClaims>
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="SecondaryEmailVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="email" Required="true" />
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="executed-SelfAsserted-Input" DefaultValue="true" />
    <OutputClaim ClaimTypeReferenceId="authenticationSource" />
    <OutputClaim ClaimTypeReferenceId="newUser" />
  </OutputClaims>
  <ValidationTechnicalProfiles>
    <ValidationTechnicalProfile ReferenceId="AAD-UserWriteUsingLogonEmail" />
  </ValidationTechnicalProfiles>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

保存声明Persist claims

不使用 PersistedClaims 元素。The PersistedClaims element is not used. 自断言技术配置文件不会将数据持久保存到 Azure AD B2C。The self-asserted technical profile doesn't persist the data to Azure AD B2C. 而是改为调用负责保留数据的验证技术配置文件。Instead, a call is made to a validation technical profile that's responsible for persisting the data. 例如,注册策略使用 LocalAccountSignUpWithLogonEmail 自断言技术配置文件来收集新用户配置文件。For example, the sign-up policy uses the LocalAccountSignUpWithLogonEmail self-asserted technical profile to collect the new user profile. LocalAccountSignUpWithLogonEmail 技术配置文件调用验证技术配置文件来在 Azure AD B2C 中创建帐户。The LocalAccountSignUpWithLogonEmail technical profile calls the validation technical profile to create the account in Azure AD B2C.

验证技术配置文件Validation technical profiles

验证技术配置文件用于验证部分或所有引用技术配置文件的输出声明。A validation technical profile is used for validating some or all of the output claims of the referencing technical profile. 验证技术配置文件的输入声明必须出现在自断言技术配置文件的输出声明中。The input claims of the validation technical profile must appear in the output claims of the self-asserted technical profile. 验证技术配置文件将验证用户输入,并可以向用户返回错误。The validation technical profile validates the user input and can return an error to the user.

验证技术配置文件可以是策略中的任何技术配置文件,例如 Azure Active DirectoryREST API 技术配置文件。The validation technical profile can be any technical profile in the policy, such as Azure Active Directory or a REST API technical profiles. 在上一示例中,LocalAccountSignUpWithLogonEmail 技术配置文件会验证 signinName 是否存在于目录中。In the previous example, the LocalAccountSignUpWithLogonEmail technical profile validates that the signinName does not exist in the directory. 如果不存在,验证技术配置文件会创建一个本地帐户,并返回 objectId、authenticationSource、newUser。If not, the validation technical profile creates a local account and returns the objectId, authenticationSource, newUser. SelfAsserted-LocalAccountSignin-Email 技术配置文件调用 login-NonInteractive 验证技术配置文件来验证用户凭据。The SelfAsserted-LocalAccountSignin-Email technical profile calls the login-NonInteractive validation technical profile to validate the user credentials.

此外,你也可以使用你的业务逻辑调用 REST API 技术配置文件,覆盖输入声明或通过进一步与企业业务线应用程序集成来丰富用户数据。You can also call a REST API technical profile with your business logic, overwrite input claims, or enrich user data by further integrating with corporate line-of-business application. 有关详细信息,请参阅验证技术配置文件For more information, see Validation technical profile

元数据Metadata

AttributeAttribute 必选Required 说明Description
setting.operatingMode 1setting.operatingMode 1 No 对于登录页面,此属性可控制用户名字段的行为,如输入验证和错误消息。For a sign-in page, this property controls the behavior of the username field, such as input validation and error messages. 预期的值为 UsernameEmailExpected values: Username or Email.
AllowGenerationOfClaimsWithNullValuesAllowGenerationOfClaimsWithNullValues No 允许生成值为 NULL 的声明。Allow to generate a claim with null value. 例如,在用户未选中复选框的情况下。For example, in a case user doesn't select a checkbox.
ContentDefinitionReferenceIdContentDefinitionReferenceId Yes 与此技术配置文件关联的内容定义的标识符。The identifier of the content definition associated with this technical profile.
EnforceEmailVerificationEnforceEmailVerification No 对于注册或配置文件编辑,强制实施电子邮件验证。For sign-up or profile edit, enforces email verification. 可能的值为 true(默认)或 falsePossible values: true (default), or false.
setting.retryLimitsetting.retryLimit No 控制用户可以尝试提供数据的次数,所提供数据将根据验证技术配置文件进行检查。Controls the number of times a user can try to provide the data that is checked against a validation technical profile. 例如,用户尝试注册已经存在的帐户,而且一直尝试,直到达到限制。For example, a user tries to sign-up with an account that already exists and keeps trying until the limit reached.
SignUpTarget 1SignUpTarget 1 No 注册目标交换标识符。The signup target exchange identifier. 当用户单击“注册”按钮时,Azure AD B2C 将执行指定的交换标识符。When the user clicks the sign-up button, Azure AD B2C executes the specified exchange identifier.
setting.showCancelButtonsetting.showCancelButton No 显示“取消”按钮。Displays the cancel button. 可能的值为 true(默认)或 falsePossible values: true (default), or false
setting.showContinueButtonsetting.showContinueButton No 显示“继续”按钮。Displays the continue button. 可能的值为 true(默认)或 falsePossible values: true (default), or false
setting.showSignupLink 2setting.showSignupLink 2 No 显示“注册”按钮。Displays the sign-up button. 可能的值为 true(默认)或 falsePossible values: true (default), or false
setting.forgotPasswordLinkLocation 2setting.forgotPasswordLinkLocation 2 No 显示“忘记密码”链接。Displays the forgot password link. 可能的值:AfterInput(默认值)链接显示在页面底部,或者 None(删除“忘记密码”链接)。Possible values: AfterInput (default) the link is displayed at the bottom of the page, or None removes the forgot password link.
setting.enableRememberMe 2setting.enableRememberMe 2 No 显示“使我保持登录状态”复选框。Displays the Keep me signed in checkbox. 可能的值:truefalse(默认值)。Possible values: true , or false (default).
IncludeClaimResolvingInClaimsHandlingIncludeClaimResolvingInClaimsHandling   No 对于输入和输出声明,指定声明解析是否包含在技术配置文件中。For input and output claims, specifies whether claims resolution is included in the technical profile. 可能的值:truefalse (默认值)。Possible values: true, or false (default). 若要使用技术配置文件中的声明解析程序,请将此项设为 trueIf you want to use a claims resolver in the technical profile, set this to true.

说明:Notes:

  1. 可用于内容定义 DataUri 类型 unifiedsspunifiedssdAvailable for content definition DataUri type of unifiedssp, or unifiedssd.
  2. 可用于内容定义 DataUri 类型 unifiedsspunifiedssdAvailable for content definition DataUri type of unifiedssp, or unifiedssd. 页面布局版本 1.1.0 及更高版本。Page layout version 1.1.0 and above.

加密密钥Cryptographic keys

不使用“CryptographicKeys” 元素。The CryptographicKeys element is not used.