使用 Azure Active Directory B2C 中的 HTML 模板自定义用户界面

开始之前,请使用上面的选择器选择要配置的策略类型。 Azure AD B2C 提供了两种定义用户如何与应用程序交互的方法:通过预定义的用户流,或者通过可完全配置的自定义策略。 对于每种方法,本文中所需的步骤都不同。

对 Azure Active Directory B2C (Azure AD B2C) 向客户显示的用户界面进行品牌设计和自定义有助于在应用程序中提供无缝的用户体验。 这些体验包括注册、登录、个人资料编辑和密码重置。 本文介绍了自定义用户界面 (UI) 的方法。

提示

如果只希望修改用户流页面的横幅徽标、背景图像和背景色,则可以尝试公司品牌功能。

自定义 HTML 和 CSS 概述

Azure AD B2C 使用跨域资源共享 (CORS) 在客户的浏览器中运行代码。 在运行时,将从你在用户流或自定义策略中指定的 URL 加载内容。 用户体验中的每个页面从你为该页面指定的 URL 加载其内容。 从 URL 加载内容后,该内容将与 Azure AD B2C 插入的 HTML 片段合并,然后向客户显示页面。

自定义页面内容边距

自定义 HTML 页面内容

使用自己的品牌打造创建 HTML 页面来提供自定义页面内容。 此页面可以是静态 *.html 页,也可以是动态页,如 .NET、Node.js 或 PHP。

你的自定义页面内容可以包含任何 HTML 元素,包括 CSS 和 JavaScript,但不能包含不安全的元素(如 iframe)。 唯一必需的元素是将 id 设置为 api 的 div 元素,例如 HTML 页面中的 <div id="api"></div> 元素。

<!DOCTYPE html>
<html>
<head>
    <title>My Product Brand Name</title>
</head>
<body>
    <div id="api"></div>
</body>
</html>

自定义默认 Azure AD B2C 页面

你可以自定义 Azure AD B2C 默认页面内容,而无需从头开始创建自定义页面内容。

下表列出了 Azure AD B2C 提供的默认页面内容。 下载文件,将其作为创建自己的自定义页面的起点。

默认页 说明 内容定义 ID
(仅自定义策略)
exception.html 错误页面。 遇到异常或错误时显示此页面。 api.error
selfasserted.html 自断言页面。 将此文件作为社交帐户注册页、本地帐户注册页、本地帐户登录页面、密码重置等的自定义页面内容。 该窗体可以包含各种输入控件,如文本输入框、密码输入框、单选按钮、单选下拉框和多选复选框。 api.localaccountsigninapi.localaccountsignupapi.localaccountpasswordresetapi.selfasserted
multifactor-1.0.0.html 多重身份验证页面 在此页面上,用户可以在注册或登录期间(使用文字或语音)验证其电话号码。 api.phonefactor
updateprofile.html 个人资料更新页面。 此页面包含用户在更新其个人资料时可以访问的窗体。 除了密码输入字段之外,此页面类似于社交帐户注册页面。 api.selfasserted.profileupdate
unified.html 统一注册或登录页面。 此页面处理用户注册和登录过程。 用户可以使用企业标识提供者、社交标识提供者或本地帐户。 api.signuporsignin

承载页面内容

使用自己的 HTML 和 CSS 文件自定义 UI 时,可将 UI 内容托管在支持 CORS 的任何公用 HTTPS 终结点上。 例如,Azure Blob 存储Azure 应用服务、Web 服务器、CDN、AWS S3 或文件共享系统。

使用自定义页面内容的准则

  • 在 HTML 文件中包含外部资源(如媒体、CSS 和 JavaScript 文件)时,请使用绝对 URL。
  • 使用页面布局版本 1.2.0 和更高版本,你可以在 HTML 标记中添加 data-preload="true" 属性,以控制 CSS 和 JavaScript 的加载顺序。 对于 data-preload="true",该页面将在向用户显示之前进行构造。 此属性可通过预加载 CSS 文件来防止页面“闪烁”,而不会向用户显示不带样式的 HTML。 以下 HTML 代码片段演示了如何使用 data-preload 标记。
    <link href="https://path-to-your-file/sample.css" rel="stylesheet" type="text/css" data-preload="true"/>
    
  • 建议你从默认页面内容开始,然后在其上构建。
  • 你可以在自定义内容中包含 JavaScript
  • 支持的浏览器版本:
    • Internet Explorer 11、10 和 Microsoft Edge
    • 对 Internet Explorer 9 和 8 的支持有限
    • Google Chrome 42.0 和更高版本
    • Mozilla Firefox 38.0 和更高版本
    • 适用于 iOS 和 macOS 的 Safari 版本 12 及更高版本
  • 由于安全限制,Azure AD B2C 不支持 frameiframeform HTML 元素。

本地化内容

可通过在 Azure AD B2C 租户中启用语言自定义来本地化 HTML 内容。 启用此功能可让 Azure AD B2C 将 OpenID Connect 参数 ui_locales 转发到终结点。 内容服务器可使用此参数提供特定语言的 HTML 页。

备注

Azure AD B2C 不会将 OpenID Connect 参数(例如 ui_locales)传递到异常页

可以基于所用的区域设置从不同位置拉取内容。 在已启用 CORS 的终结点中,可以设置文件夹结构以托管特定语言的内容。 如果使用通配符值 {Culture:RFC5646},则会调用正确的语言。

例如,自定义的页面 URI 可能类似于以下内容:

https://contoso.blob.core.chinacloudapi.cn/{Culture:RFC5646}/myHTML/unified.html

可以通过从以下位置提取内容来加载法语页面:

https://contoso.blob.core.chinacloudapi.cn/fr/myHTML/unified.html

自定义页面内容演练

下面是该过程的概述:

  1. 准备一个位置以托管自定义页面内容(可公开访问、启用 CORS 的 HTTPS 终结点)。
  2. 下载并自定义默认页面内容文件,例如 unified.html
  3. 将自定义页面内容发布于公开可用的 HTTPS 终结点。
  4. 为 Web 应用设置跨源资源共享 (CORS)。
  5. 将策略指向自定义策略内容 URI。

必备条件

1. 创建 HTML 内容

在标题中使用产品的品牌名称创建 HTML 内容。

  1. 复制以下 HTML 代码段。 这是一段采用适当格式的 HTML5 代码,它在“<body>”标签中包含名为“<div id="api"></div>”的空元素。 此元素指示要在何处插入 Azure AD B2C 内容。

    <!DOCTYPE html>
    <html>
    <head>
        <title>My Product Brand Name</title>
    </head>
    <body>
        <div id="api"></div>
    </body>
    </html>
    
  2. 将复制的片段粘贴在文本编辑器中

  3. 使用 CSS 设置 Azure AD B2C 插入页面的 UI 元素的样式。 以下示例显示了一个简单的 CSS 文件,其中还包含注册注入 HTML 元素的设置:

    h1 {
      color: blue;
      text-align: center;
    }
    .intro h2 {
      text-align: center;
    }
    .entry {
      width: 400px ;
      margin-left: auto ;
      margin-right: auto ;
    }
    .divider h2 {
      text-align: center;
    }
    .create {
      width: 400px ;
      margin-left: auto ;
      margin-right: auto ;
    }
    
  4. 将文件另存为“customize-ui.html”。

备注

由于安全限制,如果使用 login.partner.microsoftonline.cn,将删除 HTML 窗体元素。 如果要在自定义 HTML 内容中使用 HTML 窗体元素,请使用 b2clogin.cn

2. 创建 Azure Blob 存储帐户

在本文中,我们使用 Azure Blob 存储来托管内容。 可以选择将内容托管在 Web 服务器上,但必须在 Web 服务器上启用 CORS

若要在 Blob 存储中托管 HTML 内容,请执行以下步骤:

  1. 登录 Azure 门户
  2. 在“中心”菜单上,选择“新建” > “存储” > “存储帐户”。
  3. 为存储帐户选择一个 订阅
  4. 创建一个 资源组 或选择现有的资源组。
  5. 为存储帐户输入唯一的 名称
  6. 为存储帐户选择 地理位置
  7. “部署模型”可保留为“Resource Manager”。
  8. “性能”可保留为“标准”。
  9. 将“帐户类型”更改为“Blob 存储”。
  10. “复制”可保留为“RA-GRS”。
  11. “访问层”可保留为“热”。
  12. 选择“查看 + 创建”以创建存储帐户。 部署完成后,将自动打开“存储帐户”页。

2.1 创建容器

若要在 Blob 存储中创建公共容器,请执行以下步骤:

  1. 在左侧菜单的“BLOB 服务”下,选择“Blob”。
  2. 选择“容器”。
  3. 对于“名称”,请输入“root”。 该名称可以是你选择的名称(例如“contoso”),但为简单起见,此示例中我们将使用“root”。
  4. 对于“公共访问级别”,请选择“Blob”,然后选择“确定”。
  5. 选择“root”以打开新容器。

2.2 上传自定义页面内容文件

  1. 选择“上传”。
  2. 选择“选择文件”旁边的文件夹图标。
  3. 导航到“customize-ui.html”并将其选中,这是你之前在“页面 UI 自定义”部分中创建的。
  4. 如果要上传到子文件夹,请展开“高级”,然后在“上传到文件夹”中输入文件夹名称。
  5. 选择“上传”。
  6. 选择你已上传的“customize-ui.html blob”。
  7. 在“URL”文本框的右侧,选择“复制到剪贴板”图标以将 URL 复制到剪贴板。
  8. 在 web 浏览器中,导航到复制的 URL,以验证上传的 blob 是否可访问。 如果它不可访问,例如遇到 ResourceNotFound 错误,请确保将容器访问类型设置为“blob”。

3. 配置 CORS

通过执行以下步骤,将 Blob 存储配置为跨域资源共享:

  1. 在菜单中,选择“CORS”。
  2. 对于“允许的源”,请输入 https://your-tenant-name.b2clogin.cn。 将 your-tenant-name 替换为 Azure AD B2C 租户的名称。 例如,https://fabrikam.b2clogin.cn。 输入租户名称时全部使用小写字母。
  3. 对于“允许的方法”,请同时选择 GETOPTIONS
  4. 对于“允许的标头”,请输入一个星号 (*)。
  5. 对于“公开的标头”,请输入一个星号 (*)。
  6. 对于“最大期限”,请输入 200。
  7. 选择“保存”。

3.1 测试 CORS

通过执行以下步骤验证是否已准备就绪:

  1. 重复“配置 CORS”步骤。 对于“允许的源”,请输入 https://www.test-cors.org
  2. 导航到 www.test-cors.org
  3. 对于“远程 URL”框,请粘贴 HTML 文件的 URL。 例如 https://your-account.blob.core.chinacloudapi.cn/root/azure-ad-b2c/unified.html
  4. 选择“发送请求”。 结果应为 XHR status: 200。 如果收到错误,请确保 CORS 设置正确。 可能还需要清除浏览器缓存,或通过按 Ctrl+Shift+P 打开专用浏览会话。

4. 更新用户流

  1. 选择 Azure 门户左上角的“所有服务”,然后搜索并选择“Azure AD B2C” 。
  2. 选择“用户流”,然后选择“B2C_1_signupsignin1”用户流。
  3. 选择“页面布局”,然后在“统一注册或登录页面”下,对“使用自定义页面内容”单击“是” 。
  4. 在“自定义页面 URI”中,输入之前记录的“custom-ui.html”文件的 URI。
  5. 在页面顶部,选择“保存”。

5. 测试用户流

  1. 在 Azure AD B2C 租户中选择“用户流”,然后选择“B2C_1_signupsignin1”用户流。
  2. 在该页顶部,单击“运行用户流”。
  3. 单击“运行用户流”按钮。

应该会看到类似于以下示例的页面,其中元素基于所创建的 CSS 文件集中在一起:

显示带有自定义 UI 元素的注册或登录页的 Web 浏览器

4. 修改扩展文件

要配置 UI 自定义,请将“ContentDefinition”及其子元素从基本文件复制到扩展文件。

  1. 打开策略的基文件。 例如,SocialAndLocalAccounts/``TrustFrameworkBase.xml。 此基本文件是自定义策略初学者包中包含的策略文件之一,你应该已在先决条件自定义策略入门中获取。

  2. 搜索并复制 ContentDefinitions 元素的全部内容。

  3. 打开扩展文件, 例如,TrustFrameworkExtensions.xml。 搜索 BuildingBlocks 元素。 如果该元素不存在,请添加该元素。

  4. 粘贴作为 BuildingBlocks 元素的子元素复制的 ContentDefinitions 元素的全部内容。

  5. 在复制的 XML 中搜索包含 Id="api.signuporsignin" 的 ContentDefinition 元素。

  6. 将 LoadUri 的值更改为上传到存储的 HTML 文件的 URL。 例如,https://your-storage-account.blob.core.chinacloudapi.cn/your-container/customize-ui.html

    自定义策略应如下代码片段所示:

    <BuildingBlocks>
      <ContentDefinitions>
        <ContentDefinition Id="api.signuporsignin">
          <LoadUri>https://your-storage-account.blob.core.chinacloudapi.cn/your-container/customize-ui.html</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>
        </ContentDefinition>
      </ContentDefinitions>
    </BuildingBlocks>
    
  7. 保存扩展文件。

5. 上传并测试已更新的自定义策略

5.1 上传自定义策略

  1. 请确保使用包含 Azure AD B2C 租户的目录,方法是选择顶部菜单中的“目录 + 订阅”筛选器,然后选择包含租户的目录。
  2. 搜索并选择“Azure AD B2C”。
  3. 在“策略”下,选择“Identity Experience Framework”。
  4. 选择“上传自定义策略”。
  5. 上传以前已更改的扩展文件。

5.2 通过使用“立即运行”测试自定义策略

  1. 选择已上传的策略,然后选择“立即运行”。
  2. 现在,应该可以使用电子邮件地址进行注册了。

配置动态自定义页面内容 URI

使用 Azure AD B2C 自定义策略可在 URL 路径中发送参数,或查询字符串。 通过将该参数传递到 HTML 终结点,可以动态更改页面内容。 例如,可以基于从 Web 或移动应用程序传递的参数,更改 Azure AD B2C 注册或登录页面上的背景图像。 参数可以是任何声明解析程序,如应用程序 ID、语言 ID 或自定义查询字符串参数,例如 campaignId

发送查询字符串参数

若要发送查询字符串参数,请在信赖方策略中添加 ContentDefinitionParameters 元素,如下所示。

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <UserJourneyBehaviors>
    <ContentDefinitionParameters>
        <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
        <Parameter Name="lang">{Culture:LanguageName}</Parameter>
        <Parameter Name="appId">{OIDC:ClientId}</Parameter>
    </ContentDefinitionParameters>
    </UserJourneyBehaviors>
    ...
</RelyingParty>

在内容定义中,将 LoadUri 的值更改为 https://<app_name>.chinacloudsites.cn/home/unified。 自定义策略 ContentDefinition 应如下代码片段所示:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://<app_name>.chinacloudsites.cn/home/unified</LoadUri>
  ...
</ContentDefinition>

当 Azure AD B2C 加载页面时,它会调用你的 web 服务器终结点:

https://<app_name>.chinacloudsites.cn/home/unified?campaignId=123&lang=fr&appId=f893d6d3-3b6d-480d-a330-1707bf80ebea

动态页内容 URI

可以根据所使用的参数从不同位置拉取内容。 在启用 CORS 的终结点中,设置文件夹结构以托管内容。 例如,可以按以下结构组织内容。 每个语言/html 文件的根文件夹/文件夹。 例如,自定义的页面 URI 可能类似于以下内容:

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

Azure AD B2C 为语言发送两个字母 ISO 代码,法语为 fr

https://contoso.blob.core.chinacloudapi.cn/fr/myHTML/unified.html

示例模板

可以在以下位置找到用于 UI 自定义的示例模板:

git clone https://github.com/azure-ad-b2c/html-templates

本项目包含以下模板:

使用本示例:

  1. 将存储库克隆到本地计算机。 选择模板文件夹 /AzureBlue/MSA/classic

  2. 将模板文件夹和 /src 文件夹下的所有文件上传到 Blob 存储,如前一部分中所述。

  3. 接下来,打开模板文件夹中的每个 \*.html 文件。 然后,将 https://login.partner.microsoftonline.cn URL 的所有实例替换为在步骤 2 中上传的 URL。 例如:

    发件人:

    https://login.partner.microsoftonline.cn/templates/src/fonts/segoeui.WOFF
    

    到:

    https://your-storage-account.blob.core.chinacloudapi.cn/your-container/templates/src/fonts/segoeui.WOFF
    
  4. 保存 \*.html 文件并将其上传到 Blob 存储。

  5. 现在,如前文所述,修改策略,使其指向 HTML 文件。

  6. 如果发现缺少字体、图像或 CSS,请检查扩展策略和 \*.html 文件中的引用。

在自定义 HTML 中使用公司品牌打造资产

若要在自定义 HTML 中使用公司品牌打造资产,请在标记 <div id="api"> 外添加以下标记。 图像源被替换为背景图像和横幅徽标的图像源。

<img data-tenant-branding-background="true" />
<img data-tenant-branding-logo="true" alt="Company Logo" />

后续步骤

了解如何启用客户端 JavaScript 代码