通过

定义采用 Azure Active Directory B2C 中自定义策略的自断言技术配置文件

  • 项目

注意

在 Azure Active Directory B2C 中，自定义策略主要用于解决复杂的情况。 在大多数情况下，建议你使用内置用户流。 如果尚未这样做，请从 Active Directory B2C 中的自定义策略入门了解自定义策略新手包。

在 Azure Active Directory B2C (Azure AD B2C) 中用户需要提供输入的所有交互都属于自我断言技术配置文件。 例如，注册页面、登录页面或密码重置页面。

协议

“Protocol”元素的“Name”属性必须设置为 Proprietary。 “handler” 属性必须包含 Azure AD B2C 用来自断言的协议处理程序程序集的完全限定名称：Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

下面的示例显示了电子邮件注册的自断言技术配置文件：

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

输入声明

在自断言技术配置文件中，你可以使用“InputClaims”和“InputClaimsTransformations”元素预填充自断言页面上出现的声明的值（显示声明） 。 例如，在编辑配置文件策略中，用户旅程首先从 Azure AD B2C 目录服务读取用户配置文件，然后自断言技术配置文件使用用户配置文件中存储的用户数据设置输入声明。 这些声明是从用户配置文件中收集的，然后呈现给可以编辑现有数据的用户。

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

显示声明

“DisplayClaims”元素包含要呈现在屏幕上用于从用户处收集数据的声明列表 。 若要预填充显示声明的值，请使用前面介绍的输入声明。 另外，此元素还可能包含默认值。

“DisplayClaims”中的声明顺序指定 Azure AD B2C 在屏幕上呈现声明的顺序 。 若要强制用户提供特定声明的值，请将“DisplayClaim”元素的“Required”属性设置为 true。

“DisplayClaims”集合中的“ClaimType”元素需要将“UserInputType”元素设置为 Azure AD B2C 支持的任意用户输入类型 。 例如，TextBox 或 DropdownSingleSelect。

添加对 DisplayControl 的引用

在显示声明集合中，可以包含对已创建的 DisplayControl 的引用。 显示控件是一个具有特殊功能的用户界面元素，可以与 Azure AD B2C 后端服务进行交互。 它允许用户在页面上执行某些操作，这些操作在后端调用验证技术配置文件。 例如，验证电子邮件地址、电话号码或客户会员号。

以下示例 TechnicalProfile 阐释了如何配合使用显示声明和显示控件。

  • 第一个显示声明引用收集和验证电子邮件地址的 emailVerificationControl 显示控件。
  • 第六个显示声明引用收集和验证电话号码的 phoneVerificationControl 显示控件。
  • 其他显示声明为 ClaimTypes，要从用户处收集。
<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>

如上所述，引用显示控件的显示声明可以自己运行验证，例如，验证电子邮件地址。 此外，自断言页面支持在执行下一个业务流程步骤之前使用验证技术配置文件来验证整个页面，包括任何用户输入（声明类型或显示控件）。

谨慎细心地配合使用显示声明和输出声明

如果在自断言技术配置文件中指定一个或多个“DisplayClaim”元素，则必须对要从用户处收集的、要在屏幕上显示的每个声明使用 DisplayClaim 。 至少包含一个显示声明的自断言技术配置文件中不显示任何输出声明。

请思考以下示例，其中 age 声明被定义为基本策略中的输出声明 。 在将任何显示声明添加到自断言技术配置文件之前，屏幕上会显示 age 声明，用于从用户处收集数据：

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

如果继承了该基本策略的叶策略随后指定 officeNumber 作为显示声明 ：

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

屏幕上不再向用户显示基本策略中的 age 声明 - 它实际上处于“隐藏”状态。若要显示 age 声明并从用户处收集“年龄”值，需要将 age 添加到 DisplayClaim。

输出声明

“OutputClaims”元素包含要返回到下一个业务流程步骤的的声明列表 。 “DefaultValue”属性只有在从未设置过声明的情况下才会生效 。 如果在上一业务流程步骤中设置过，即使用户将值留空，默认值也不会生效。 若要强制使用默认值，请将“AlwaysUseDefaultValue” 属性设置为 true。

出于安全原因，密码声明值（UserInputType 设置为 Password）仅可用于自断言技术配置文件的验证技术配置文件。 在下一个业务流程步骤中，不能使用密码声明。

注意

在以前的 Identity Experience Framework (IEF) 版本中，输出声明用于从用户处收集数据。 若要从用户处收集数据，请改用“DisplayClaims”集合 。

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。

何时应使用输出声明

在自断言技术配置文件中，输出声明集合将声明返回到下一个业务流程步骤。

在以下情况下使用输出声明：

  • 声明由输出声明转换输出 。
  • 在输出声明中设置默认值无需从用户处收集数据或从验证技术配置文件返回数据 。 LocalAccountSignUpWithLogonEmail 自断言技术配置文件将“executed-SelfAsserted-Input” 声明设置为 true。
  • 验证技术配置文件返回输出声明 - 你的技术配置文件可以调用返回某些声明的验证技术配置文件。 你需要发出声明并将其返回到用户旅程中的下一个业务流程步骤。 例如，当使用本地帐户登录时，名为 SelfAsserted-LocalAccountSignin-Email 的自断言技术配置文件会调用名为 login-NonInteractive 的验证技术配置文件。 此技术配置文件将验证用户凭据，并返回用户配置文件。 例如“userPrincipalName”、“displayName”、“givenName”和“surName”。
  • 显示控件返回输出声明 - 技术配置文件可能引用显示控件。 显示控件返回某些声明，如已验证的电子邮件地址。 你需要发出声明并将其返回到用户旅程中的下一个业务流程步骤。

以下示例演示如何使用同时包含显示声明和输出声明的自断言技术配置文件。

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

注意

在自断言技术配置文件中收集密码声明值时，该值仅在同一技术配置文件中，或由同一自断言技术配置文件引用的验证技术配置文件中可用。 执行完该自我断言技术配置文件并转移动到另一个技术配置文件时，密码的值将会丢失。 因此，密码声明只能存储在收集密码的业务流程步骤中。

输出声明注册或登录页

在合并的注册和登录页面中，使用指定 unifiedssp 或 unifiedssd 页面类型的内容定义 DataUri 元素时，请注意下面几点：

  • 仅呈现用户名和密码声明。
  • 前两个输出声明必须为用户名和密码（按此顺序）。
  • 不呈现任何其他声明；对于这些声明，你将需要设置 defaultValue 或调用声明格式验证技术配置文件。

保存声明

不使用 PersistedClaims 元素。 自断言技术配置文件不会将数据持久保存到 Azure AD B2C。 而是改为调用负责保留数据的验证技术配置文件。 例如，注册策略使用 LocalAccountSignUpWithLogonEmail 自断言技术配置文件来收集新用户配置文件。 LocalAccountSignUpWithLogonEmail 技术配置文件调用验证技术配置文件来在 Azure AD B2C 中创建帐户。

验证技术配置文件

验证技术配置文件用于验证部分或所有引用技术配置文件的输出声明。 验证技术配置文件的输入声明必须出现在自断言技术配置文件的输出声明中。 验证技术配置文件将验证用户输入，并可以向用户返回错误。

验证技术配置文件可以是策略中的任何技术配置文件，例如 Microsoft Entra ID 或 REST API 技术配置文件。 在上一示例中，LocalAccountSignUpWithLogonEmail 技术配置文件会验证 signinName 是否存在于目录中。 如果不存在，验证技术配置文件会创建一个本地帐户，并返回 objectId、authenticationSource、newUser。 SelfAsserted-LocalAccountSignin-Email 技术配置文件调用 login-NonInteractive 验证技术配置文件来验证用户凭据。

此外，你也可以使用你的业务逻辑调用 REST API 技术配置文件，覆盖输入声明或通过进一步与企业业务线应用程序集成来丰富用户数据。 有关详细信息，请参阅验证技术配置文件

注意

仅当用户输入内容时，才会触发验证技术配置文件。 如果仅是为了使用 ValidationTechnicalProfile 元素的 ContinueOnError 属性，那么无法创建空的自断言技术配置文件来调用验证技术配置文件。 只能从请求用户输入的自断言技术配置文件，或者从用户旅程中的业务流程步骤调用验证技术配置文件。

元数据

Attribute 必须 说明
setting.operatingMode 1 否 对于登录页面，此属性可控制用户名字段的行为，如输入验证和错误消息。 预期的值为 Username 或 Email。 查看此元数据的实时演示。
AllowGenerationOfClaimsWithNullValues 否 允许生成值为 NULL 的声明。 例如，在用户未选中复选框的情况下。
ContentDefinitionReferenceId 是 与此技术配置文件关联的内容定义的标识符。
EnforceEmailVerification 否 对于注册或配置文件编辑，强制实施电子邮件验证。 可能的值为 true（默认）或 false。
setting.retryLimit 否 控制用户可以尝试提供数据的次数，所提供数据将根据验证技术配置文件进行检查。 例如，用户尝试注册已经存在的帐户，而且一直尝试，直到达到限制。 查看此元数据的实时演示。
SignUpTarget 1 否 注册目标交换标识符。 当用户单击“注册”按钮时，Azure AD B2C 将执行指定的交换标识符。
setting.showCancelButton 否 显示“取消”按钮。 可能的值为 true（默认）或 false。 查看此元数据的实时演示。
setting.showContinueButton 否 显示“继续”按钮。 可能的值为 true（默认）或 false。 查看此元数据的实时演示。
setting.showSignupLink 2 否 显示“注册”按钮。 可能的值为 true（默认）或 false。 查看此元数据的实时演示。
setting.forgotPasswordLinkLocation 2 否 显示“忘记密码”链接。 可能的值：AfterLabel（默认值），它直接在标签后面（如果没有标签，则在密码输入字段后面）显示链接；AfterInput，它在密码输入字段后面显示链接；AfterButtons，它在按钮后面的窗体底部显示链接；或者 None，它会删除“忘记密码”链接。 查看此元数据的实时演示。
setting.enableRememberMe 2 否 显示使我保持登录状态复选框。 可能的值：true 或 false（默认值）。 此元数据的实时演示。
setting.inputVerificationDelayTimeInMilliseconds 3 否 通过等待用户停止键入后再验证该值来改善用户体验。 默认值为 2000 毫秒。 查看此元数据的实时演示。
IncludeClaimResolvingInClaimsHandling 否 对于输入和输出声明，指定声明解析是否包含在技术配置文件中。 可能的值：true 或 false（默认值）。 若要使用技术配置文件中的声明解析程序，请将此项设为 true。
setting.forgotPasswordLinkOverride 4 否 密码重置声明要执行交换。 有关详细信息，请参阅自助式密码重置。
setting.showHeading 否 指定“用户详细信息”标题元素是否应当可见。 可能的值为 true（默认）或 false。

注意：

  1. 可用于内容定义 DataUri 类型 unifiedssp 或 unifiedssd。
  2. 可用于内容定义 DataUri 类型 unifiedssp 或 unifiedssd。 页面布局版本 1.1.0 及更高版本。
  3. 可用于页面布局版本 1.2.0 及更高版本。
  4. 可用于内容定义 DataUri 类型 unifiedssp。 页面布局版本 2.1.2 及更高版本。

加密密钥

不使用“CryptographicKeys”元素。