ContentDefinitionsContentDefinitions

备注

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

可以自定义任何自我断言技术配置文件的外观。You can customize the look and feel of any self-asserted technical profile. Azure Active Directory B2C (Azure AD B2C) 在客户的浏览器中运行代码,并使用称为“跨域资源共享”(CORS) 的现代方法。Azure Active Directory B2C (Azure AD B2C) runs code in your customer's browser and uses a modern approach called Cross-Origin Resource Sharing (CORS).

若要自定义用户界面,请在包含自定义 HTML 内容的 ContentDefinition 元素中指定一个 URL。To customize the user interface, you specify a URL in the ContentDefinition element with customized HTML content. 在自我断言技术配置文件或 OrchestrationStep 中,指向该内容定义标识符。In the self-asserted technical profile or OrchestrationStep, you point to that content definition identifier. 内容定义可以包含 LocalizedResourcesReferences 元素,该元素指定要加载的本地化资源列表。The content definition may contain a LocalizedResourcesReferences element that specifies a list of localized resources to load. Azure AD B2C 将用户界面元素与从 URL 加载的 HTML 内容合并,然后向用户显示页面。Azure AD B2C merges user interface elements with the HTML content that's loaded from your URL and then displays the page to the user.

ContentDefinitions 元素包含可在用户旅程中使用的 HTML5 模板的 URL。The ContentDefinitions element contains URLs to HTML5 templates that can be used in a user journey. HTML5 页面 URI 用于指定的用户界面步骤。The HTML5 page URI is used for a specified user interface step. 例如,登录或注册、密码重置或错误页面。For example, the sign-in or sign-up, password reset, or error pages. 可以通过重写 HTML5 文件的 LoadUri 来修改外观。You can modify the look and feel by overriding the LoadUri for the HTML5 file. 可根据需要创建新的内容定义。You can create new content definitions according to your needs. 此元素可以包含对 Localization 元素中指定的本地化标识符的本地化资源引用。This element may contain a localized resources reference, to the localization identifier specified in the Localization element.

以下示例演示了本地化资源的内容定义标识符和定义:The following example shows the content definition identifier and the definition of localized resources:

<ContentDefinition Id="api.localaccountsignup">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Local account sign up page</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.localaccountsignup.en" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.localaccountsignup.es" />
    ...

LocalAccountSignUpWithLogonEmail 自我断言技术配置文件的元数据包含设置为 api.localaccountsignup 的内容定义标识符 ContentDefinitionReferenceIdThe metadata of the LocalAccountSignUpWithLogonEmail self-asserted technical profile contains the content definition identifier ContentDefinitionReferenceId set to api.localaccountsignup

<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="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    ...
  </Metadata>
  ...

ContentDefinitionContentDefinition

ContentDefinition 元素包含以下属性:The ContentDefinition element contains the following attribute:

AttributeAttribute 必选Required 说明Description
IDId Yes 内容定义标识符。An identifier for a content definition. 其值为本页稍后的“内容定义 ID”部分指定的值。 The value is one specified in the Content definition IDs section later in this page.

ContentDefinition 元素包含以下元素:The ContentDefinition element contains the following elements:

元素Element 出现次数Occurrences 说明Description
LoadUriLoadUri 1:11:1 一个字符串,包含内容定义 HTML5 页面的 URL。A string that contains the URL of the HTML5 page for the content definition.
RecoveryUriRecoveryUri 1:11:1 一个字符串,包含用于显示内容定义相关错误的 HTML 页面的 URL。A string that contains the URL of the HTML page for displaying an error relating to the content definition. 当前未使用,此值必须为 ~/common/default_page_error.htmlNot currently used, the value must be ~/common/default_page_error.html.
DataUriDataUri 1:11:1 一个字符串,包含一个 HTML 文件的相对 URL,该文件提供要为步骤调用的用户体验。A string that contains the relative URL of an HTML file that provides the user experience to invoke for the step.
元数据Metadata 0:10:1 一个键/值对集合,包含内容定义使用的元数据。A collection of key/value pairs that contains the metadata utilized by the content definition.
LocalizedResourcesReferencesLocalizedResourcesReferences 0:10:1 本地化的资源引用集合。A collection of localized resources references. 使用此元素可以自定义用户界面和声明属性的本地化。Use this element to customize the localization of a user interface and claims attribute.

DataUriDataUri

DataUri 元素用于指定页面标识符。The DataUri element is used to specify the page identifier. Azure AD B2C 使用页面标识符来加载和启动 UI 元素与客户端 JavaScript。Azure AD B2C uses the page identifier to load and initiate UI elements and client side JavaScript. 值的格式为 urn:com:microsoft:aad:b2c:elements:page-name:versionThe format of the value is urn:com:microsoft:aad:b2c:elements:page-name:version. 下表列出了可以使用的页面标识符。The following table lists the page identifiers you can use.

页面标识符Page identifier 说明Description
globalexception 遇到异常或错误时显示错误页面。Displays an error page when an exception or an error is encountered.
providerselectionidpselectionproviderselection, idpselection 列出可供用户在登录期间选择的标识提供者。Lists the identity providers that users can choose from during sign-in.
unifiedssp 显示一个窗体,用于通过基于电子邮件地址或用户名的本地帐户进行登录。Displays a form for signing in with a local account that's based on an email address or a user name. 此值还提供“使我保持登录功能”和“忘记了密码?”This value also provides the “keep me sign-in functionality” and “Forgot your password?” 链接。link.
unifiedssd 显示一个窗体,用于通过基于电子邮件地址或用户名的本地帐户进行登录。Displays a form for signing in with a local account that's based on an email address or a user name.
multifactor 在注册或登录期间使用短信或语音来验证电话号码。Verifies phone numbers by using text or voice during sign-up or sign-in.
selfasserted 显示用于从用户收集数据的表单。Displays a form to collect data from a user. 例如,让用户创建或更新其个人资料。For example, enables users to create or update their profile.

选择页面布局Select a page layout

elements 和页面类型之间插入 contract 即可启用 JavaScript 客户端代码You can enable JavaScript client-side code by inserting contract between elements and the page type. 例如,urn:com:microsoft:aad:b2c:elements:contract:page-name:versionFor example, urn:com:microsoft:aad:b2c:elements:contract:page-name:version.

备注

此功能目前以公共预览版提供。This feature is in public preview.

DataUriversion 部分指定内容包,其中包含的 HTML、CSS 和 JavaScript 适用于策略中的用户界面元素。The version part of the DataUri specifies the package of content containing HTML, CSS, and JavaScript for the user interface elements in your policy. 如果打算启用 JavaScript 客户端代码,则 JavaScript 所基于的元素必须是不可变的。If you intend to enable JavaScript client-side code, the elements you base your JavaScript on must be immutable. 如果它们不是不可变的,则任何更改都可能会导致用户页上出现意外行为。If they're not immutable, any changes could cause unexpected behavior on your user pages. 为了防止这些问题,请强制使用页面布局,并指定页面布局版本。To prevent these issues, enforce the use of a page layout and specify a page layout version. 这样做可以确保 JavaScript 所基于的所有内容定义不可变。Doing so ensures that all content definitions you’ve based your JavaScript on are immutable. 即使不打算启用 JavaScript,也仍然需要为页面指定页面布局版本。Even if you don’t intend to enable JavaScript, you still need to specify the page layout version for your pages.

以下示例显示版本 1.2.0DataUriselfassertedThe following example shows the DataUri of selfasserted version 1.2.0:

<ContentDefinition Id="api.localaccountpasswordreset">
<LoadUri>~/tenant/templates/AzureBlue/selfAsserted.cshtml</LoadUri>
<RecoveryUri>~/common/default_page_error.html</RecoveryUri>
<DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:1.2.0</DataUri>
<Metadata>
    <Item Key="DisplayName">Local account change password page</Item>
</Metadata>
</ContentDefinition>

迁移到页面布局Migrating to page layout

值的格式必须包含单词 contracturn:com:microsoft:aad:b2c:elements:contract:page-name:versionThe format of the value must contain the word contract: urn:com:microsoft:aad:b2c:elements:contract:page-name:version. 若要在使用旧 DataUri 值的自定义策略中指定页面布局,请根据下表迁移到新格式。To specify a page layout in your custom policies that use an old DataUri value, use following table to migrate to the new format.

旧 DataUri 值Old DataUri value 新 DataUri 值New DataUri value
urn:com:microsoft:aad:b2c:elements:globalexception:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.0
urn:com:microsoft:aad:b2c:elements:globalexception:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.0
urn:com:microsoft:aad:b2c:elements:idpselection:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.0
urn:com:microsoft:aad:b2c:elements:multifactor:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.0
urn:com:microsoft:aad:b2c:elements:multifactor:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.0
urn:com:microsoft:aad:b2c:elements:selfasserted:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:selfasserted:1.2.0
urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:selfasserted:1.2.0
urn:com:microsoft:aad:b2c:elements:unifiedssd:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:unifiedssd:1.2.0
urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:1.2.0
urn:com:microsoft:aad:b2c:elements:unifiedssp:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:1.2.0

元数据Metadata

Metadata 元素包含以下元素:A Metadata element contains the following elements:

元素Element 出现次数Occurrences 说明Description
ItemItem 0:n0:n 与内容定义相关的元数据。The metadata that relates to the content definition.

Metadata 元素的 Item 元素包含以下属性:The Item element of the Metadata element contains the following attributes:

AttributeAttribute 必选Required 说明Description
密钥Key Yes 元数据密钥。The metadata key.

元数据键Metadata keys

内容定义支持以下元数据项:Content definition supports following metadata items:

密钥Key 必选Required 说明Description
DisplayNameDisplayName No 一个包含内容定义名称的字符串。A string that contains the name of the content definition.

LocalizedResourcesReferencesLocalizedResourcesReferences

LocalizedResourcesReferences 元素包含以下元素:The LocalizedResourcesReferences element contains the following elements:

元素Element 出现次数Occurrences 说明Description
LocalizedResourcesReferenceLocalizedResourcesReference 1:n1:n 内容定义的本地化资源引用列表。A list of localized resource references for the content definition.

LocalizedResourcesReference 元素包含以下属性:The LocalizedResourcesReference element contains the following attributes:

AttributeAttribute 必选Required 说明Description
语言Language Yes 一个字符串,包含符合 RFC 5646“用于标识语言的标记”的策略支持的语言。A string that contains a supported language for the policy per RFC 5646 - Tags for Identifying Languages.
LocalizedResourcesReferenceIdLocalizedResourcesReferenceId Yes LocalizedResources 元素的标识符。The identifier of the LocalizedResources element.

以下示例演示包含对英语、法语和西班牙语本地化的引用的注册或登录内容定义:The following example shows a sign-up or sign-in content definition with a reference to localization for English, French and Spanish:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/default/unified.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Signin and Signup</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.signuporsignin.en" />
    <LocalizedResourcesReference Language="fr" LocalizedResourcesReferenceId="api.signuporsignin.rf" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.signuporsignin.es" />
</LocalizedResourcesReferences>
</ContentDefinition>

若要了解如何将本地化支持添加到内容定义,请参阅本地化To learn how to add localization support to your content definitions, see Localization.

内容定义 IDContent definition IDs

ContentDefinition 元素的 ID 属性指定与内容定义相关的页面类型。The ID attribute of the ContentDefinition element specifies the type of page that relates to the content definition. 该元素定义要在其中应用自定义 HTML5/CSS 模板的上下文。The element defines the context that a custom HTML5/CSS template is going to apply. 下表描述了标识体验框架识别的内容定义 ID 集及其相关的页面类型。The following table describes the set of content definition IDs that is recognized by the Identity Experience Framework, and the page types that relate to them. 可以使用任意 ID 创建自己的内容定义。You can create your own content definitions with an arbitrary ID.

IDID 默认模板Default template 说明Description
api.errorapi.error exception.cshtmlexception.cshtml 错误页面 - 遇到异常或错误时显示错误页面。Error page - Displays an error page when an exception or an error is encountered.
api.idpselectionsapi.idpselections idpSelector.cshtmlidpSelector.cshtml 标识提供者选项页面 - 列出可供用户在登录期间选择的标识提供者。Identity provider selection page - Lists identity providers that users can choose from during sign-in. 选项通常是企业标识提供者、社交标识提供者或本地帐户。The options are usually enterprise identity providers, social identity providers or local accounts.
api.idpselections.signupapi.idpselections.signup idpSelector.cshtmlidpSelector.cshtml 注册时的标识提供者选项 - 列出可供用户在注册期间选择的标识提供者。Identity provider selection for sign-up - Lists identity providers that users can choose from during sign-up. 选项通常是企业标识提供者、社交标识提供者或本地帐户。The options are usually enterprise identity providers, social identity providers or local accounts.
api.localaccountpasswordresetapi.localaccountpasswordreset selfasserted.htmlselfasserted.html 忘记了密码页面 - 显示一个窗体,用户必须填写该窗体才能发起密码重置。Forgot password page - Displays a form that users must complete to initiate a password reset.
api.localaccountsigninapi.localaccountsignin selfasserted.htmlselfasserted.html 本地帐户登录页面 - 显示一个窗体,用于通过基于电子邮件地址或用户名的本地帐户进行登录。Local account sign-in page - Displays a form for signing in with a local account that's based on an email address or a user name. 该窗体可以包含文本输入框和密码输入框。The form can contain a text input box and password entry box.
api.localaccountsignupapi.localaccountsignup selfasserted.htmlselfasserted.html 本地帐户注册页面 - 显示一个窗体,用于注册基于电子邮件地址或用户名的本地帐户。Local account sign-up page - Displays a form for signing up for a local account that's based on an email address or a user name. 该窗体可以包含各种输入控件,如文本输入框、密码输入框、单选按钮、单选下拉框和多选复选框。The form can contain various input controls, such as: a text input box, a password entry box, a radio button, single-select drop-down boxes, and multi-select check boxes.
api.phonefactorapi.phonefactor multifactor-1.0.0.cshtmlmultifactor-1.0.0.cshtml 多重身份验证页面 - 在注册或登录期间使用短信或语音来验证电话号码。Multi-factor authentication page - Verifies phone numbers, by using text or voice, during sign-up or sign-in.
api.selfassertedapi.selfasserted selfasserted.htmlselfasserted.html 社交帐户注册页面 - 显示一个窗体,用户在使用社交标识提供者的现有帐户注册时必须填写此窗体。Social account sign-up page - Displays a form that users must complete when they sign up by using an existing account from a social identity provider. 除了密码输入字段之外,此页面类似于前面的社交帐户注册页面。This page is similar to the preceding social account sign up page, except for the password entry fields.
api.selfasserted.profileupdateapi.selfasserted.profileupdate updateprofile.htmlupdateprofile.html 个人资料更新页面 - 显示用户在更新其个人资料时可以访问的窗体。Profile update page - Displays a form that users can access to update their profile. 除了密码输入字段之外,此页面类似于社交帐户注册页面。This page is similar to the social account sign up page, except for the password entry fields.
api.signuporsigninapi.signuporsignin unified.htmlunified.html 统一注册或登录页面 - 处理用户注册和登录过程。Unified sign-up or sign-in page - Handles the user sign-up and sign-in process. 用户可以使用企业标识提供者、社交标识提供者本地帐户。Users can use enterprise identity providers, social identity providers local accounts.