ContentDefinitions

重要

自 2025 年 5 月 1 日起,Azure AD B2C 将不再可供新客户购买。 在我们的常见问题解答中了解详细信息

备注

在 Azure Active Directory B2C 中,自定义策略 主要用于解决复杂场景。 对于大多数场景,我们建议您使用内置的用户流。 如果未这样做,请通过 Active Directory B2C 中的自定义策略入门来了解自定义策略初学者包。

可以自定义任何 自断言技术配置文件的外观。 Azure Active Directory B2C(Azure AD B2C)在客户的浏览器中运行代码,并使用一种称为跨域资源共享(CORS)的新式方法。

若要自定义用户界面,请在 ContentDefinition 元素中指定包含自定义 HTML 内容的 URL。 在自断言技术配置文件或 OrchestrationStep 中,指向该内容定义标识符。 内容定义可能包含 LocalizedResourcesReferences 元素,该元素指定要加载的本地化资源列表。 Azure AD B2C 将用户界面元素与从 URL 加载的 HTML 内容合并,然后向用户显示页面。

ContentDefinitions 元素包含可用于用户旅程的 HTML5 模板的 URL。 HTML5 页面 URI 用于指定的用户界面步骤。 例如,登录或注册、密码重置或错误页。 可以通过重写 HTML5 文件的 LoadUri 来修改外观。 可以根据需要创建新的内容定义。 此元素可能包含本地化资源引用,以引用本地化元素中指定的 本地化 标识符。

以下示例显示了内容定义标识符和本地化资源的定义:

<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 自断言技术配置文件的元数据包含内容定义标识符 ContentDefinitionReferenceId 设置为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>
  ...

ContentDefinition

ContentDefinition 元素包含以下属性:

特征 必选 DESCRIPTION
ID 是的 内容定义的标识符。 此值是本页后面的 内容定义 ID 部分中指定的值。

ContentDefinition 元素包含以下元素:

元素 出现次数 DESCRIPTION
LoadUri 1:1 一个字符串,其中包含内容定义的 HTML5 页面的 URL。
RecoveryUri 1:1 一个字符串,其中包含 HTML 页面的 URL,用于显示与内容定义相关的错误。 当前未使用,该值必须为 ~/common/default_page_error.html
DataUri 1:1 一个字符串,其中包含 HTML 文件的相对 URL,该文件提供为步骤调用的用户体验。
元数据 0:1 包含内容定义使用的元数据的键/值对的集合。
LocalizedResourcesReferences 0:1 本地化资源引用的集合。 使用此元素自定义用户界面和声明属性的本地化。

LoadUri

LoadUri 元素用于指定内容定义的 HTML5 页面的 URL。 Azure AD B2C 自定义策略初学者包 附带了使用 Azure AD B2C HTML 页面的内容定义。 LoadUri 以 Azure AD B2C 租户的相对路径开头~

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/templates/AzureBlue/unified.cshtml</LoadUri>
  ...
</ContentDefinition>

可以使用 HTML 模板自定义用户界面。 使用 HTML 模板时,请提供绝对 URL。 以下示例演示了 HTML 模板的内容定义:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://your-storage-account.blob.core.chinacloudapi.cn/your-container/customize-ui.html</LoadUri>
  ...
</ContentDefinition>

DataUri

DataUri 元素用于指定页面标识符。 Azure AD B2C 使用页面标识符来加载和启动 UI 元素和客户端 JavaScript。 值的格式为 urn:com:microsoft:aad:b2c:elements:page-name:version. 下表列出了可以使用的页面标识符。

页面标识符 DESCRIPTION
globalexception 在遇到异常或遇到错误时显示错误页。
providerselectionidpselection 列出用户在登录期间可从中选择的标识提供者。
unifiedssp 显示一个表单,用于使用基于电子邮件地址或用户名的本地帐户登录。 此值还提供“使我保持登录功能”和“忘记密码?”链接。
unifiedssd 显示一个表单,用于使用基于电子邮件地址或用户名的本地帐户登录。 此页标识符已弃用。 请改用 unifiedssp 页面标识符。
multifactor 在注册或登录期间使用文本或语音验证电话号码。
selfasserted 显示要从用户收集数据的窗体。 例如,允许用户创建或更新其配置文件。

选择页面布局

可以通过在页面类型之间插入contract和页面类型来启用 elements。 例如,urn:com:microsoft:aad:b2c:elements:contract:page-name:version

版本部分DataUri指定策略中用户界面元素包含 HTML、CSS 和 JavaScript 的内容包。 如果打算启用 JavaScript 客户端代码,则基于 JavaScript 的元素必须不可变。 如果它们不是不可变的,任何更改都可能导致用户页面上出现意外行为。 若要防止这些问题,请强制使用页面布局并指定页面布局版本。 这样做可确保基于 JavaScript 的所有内容定义都是不可变的。 即使不想启用 JavaScript,仍需要为页面指定页面布局版本。

以下示例显示了版本的 selfasserted1.2.0

<!-- 
<BuildingBlocks> 
  <ContentDefinitions>-->
    <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>
  <!-- 
  </ContentDefinitions> 
</BuildingBlocks> -->

迁移到页面布局

若要从旧的 DataUri 值(没有页面协定)迁移到页面布局版本,请添加后跟页面版本的单词 contract 。 使用下表从旧的 DataUri 值迁移到页面布局版本。

旧 DataUri 值 新建 DataUri 值
urn:com:microsoft:aad:b2c:elements:globalexception:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1
urn:com:microsoft:aad:b2c:elements:globalexception:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1
urn:com:microsoft:aad:b2c:elements:idpselection:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1
urn:com:microsoft:aad:b2c:elements:selfasserted:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7
urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7
urn:com:microsoft:aad:b2c:elements:unifiedssd:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:unifiedssd:1.2.1
urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5
urn:com:microsoft:aad:b2c:elements:unifiedssp:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5
urn:com:microsoft:aad:b2c:elements:multifactor:1.0.0 urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5
urn:com:microsoft:aad:b2c:elements:multifactor:1.1.0 urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5

以下示例显示了内容定义标识符和具有最新页面版本的相应 DataUri

<!-- 
<BuildingBlocks> -->
  <ContentDefinitions>
    <ContentDefinition Id="api.error">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections.signup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.signuporsignin">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.7</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted.profileupdate">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountsignup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountpasswordreset">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.phonefactor">
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5</DataUri>
    </ContentDefinition>
  </ContentDefinitions>
<!-- 
</BuildingBlocks> -->

元数据

Metadata 元素包含以下元素:

元素 出现次数 DESCRIPTION
条目 0:n 与内容定义相关的元数据。

Metadata 元素的 Item 元素包含以下属性:

特征 必选 DESCRIPTION
密钥 是的 元数据密钥。

元数据键

内容定义支持以下元数据项:

密钥 必选 DESCRIPTION
显示名称 一个包含内容定义名称的字符串。

LocalizedResourcesReferences

LocalizedResourcesReferences 元素包含以下元素:

元素 出现次数 DESCRIPTION
LocalizedResourcesReference 1:n 内容定义的本地化资源引用列表。

LocalizedResourcesReference 元素包含以下属性:

特征 必选 DESCRIPTION
语言 是的 一个字符串,其中包含每个 RFC 5646 - 标识语言的策略支持的语言。
LocalizedResourcesReferenceId 是的 LocalizedResources 元素的标识符。

以下示例演示了一个注册或登录内容定义,该定义引用了英语、法语和西班牙语的本地化:

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

若要了解如何向内容定义添加本地化支持,请参阅 本地化

内容定义 ID

ContentDefinition 元素的 ID 属性指定与内容定义相关的页面类型。 该元素定义自定义 HTML5/CSS 模板将应用的上下文。 下表描述了标识体验框架识别的内容定义 ID 集,以及与其相关的页面类型。 可以使用任意 ID 创建自己的内容定义。

身份证件 默认模板 DESCRIPTION
api.error exception.cshtml 错误页 - 在遇到异常或遇到错误时显示错误页。
api.idpselections idpSelector.cshtml 标识提供者选择页 - 列出用户可以在登录期间从中选择的标识提供者。 这些选项通常是企业标识提供者、社交标识提供者或本地帐户。
api.idpselections.signup idpSelector.cshtml 注册的标识提供者选择 - 列出用户可以在注册期间从中选择的标识提供者。 这些选项通常是企业标识提供者、社交标识提供者或本地帐户。
api.localaccountpasswordreset selfasserted.cshtml 忘记密码页 - 显示用户必须完成才能启动密码重置的窗体。
api.localaccountsignin selfasserted.cshtml 本地帐户登录页 - 显示一个表单,用于使用基于电子邮件地址或用户名的本地帐户登录。 窗体可以包含文本输入框和密码输入框。
api.localaccountsignup selfasserted.cshtml 本地帐户注册页 - 显示用于注册基于电子邮件地址或用户名的本地帐户的表单。 窗体可以包含各种输入控件,例如:文本输入框、密码输入框、单选按钮、单选下拉列表框和多选复选框。
api.phonefactor multifactor-1.0.0.cshtml 多重身份验证页 - 在注册或登录期间使用文本或语音验证电话号码。
api.selfasserted selfasserted.cshtml 社交帐户注册页 - 显示用户在使用社交标识提供者中的现有帐户注册时必须完成的表单。 此页面类似于前面的社交帐户注册页,密码输入字段除外。
api.selfasserted.profileupdate updateprofile.cshtml 配置文件更新页 - 显示用户可以访问的表单以更新其配置文件。 此页面类似于社交帐户注册页,密码输入字段除外。
api.signuporsignin unified.cshtml 统一注册或登录页 - 处理用户注册和登录过程。 用户可以使用企业标识提供者、社交标识提供者或本地帐户。

后续步骤

有关使用内容定义自定义用户界面的示例,请参阅:

使用自定义策略自定义应用程序的用户界面