在 Azure Active Directory B2C 中，使用 HTML 範本自訂使用者介面

發行項
12/05/2022

開始之前，請使用 [選擇原則類型] 選取器，選擇您要設定的原則類型。 Azure Active Directory B2C 提供兩種方法來定義使用者如何與您的應用程式互動：透過預先定義的使用者流程，或透過完全可設定的自訂原則。此文章中所需的步驟，隨各種方法而異。

為客戶所見到的 Azure Active Directory B2C (Azure AD B2C) 使用者介面，進行品牌打造與客製化，有助於使用者體驗順暢的應用程式。這些體驗包括註冊、登入、設定檔編輯與密碼重設。本文旨在介紹使用者介面 (UI) 的自訂方法。

提示

如果只想要修改使用者流程頁面的橫幅標誌、背景影像和背景色彩，可以嘗試使用公司品牌功能。

自訂 HTML 和 CSS 概觀

Azure AD B2C 使用跨原始資源分享 (CORS)的方式，在客戶的瀏覽器中執行程式碼。在執行階段期間，會從您在使用者流程或自訂原則中所指定的 URL，載入內容。使用者體驗中的每個頁面，都會從您為該頁面所指定的 URL，載入其內容。從您的 URL 載入內容之後，就會與 Azure AD B2C 所插入的 HTML 片段合併，然後才會對客戶顯示。

Custom page content margin

自訂 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 所提供的預設頁面內容。請下載這些檔案，並將其用做為製作專屬自訂頁面的起始點。

頁面	描述	範本
統一的註冊或登入	此頁面可處理使用者的註冊和登入程序。使用者可以使用企業識別提供者、社交識別提供者 (如 Facebook 或 Microsoft 帳戶) 或本機帳戶。	傳統、海洋藍和岩灰。
登入 (僅限)	登入頁面也稱為「識別提供者選取項目」。它會以本機帳戶或同盟識別提供者來處理使用者登入。使用此頁面允許登入，但不能註冊。例如，在使用者編輯設定檔之前進行。	傳統、海洋藍和岩灰。
自我判斷	使用者應該在 Azure AD B2C 提供輸入，而 Azure AD B2C 中大部分的互動為自我判斷。例如，註冊頁面、登入頁面或密碼重設頁面。使用此範本做為社交帳戶註冊頁面、本機帳戶註冊頁面、本機帳戶登入頁面、密碼重設、編輯設定檔、區塊頁面等的自訂頁面內容。此自我判斷頁面可以包含各種輸入控制項，例如文字輸入方塊、密碼輸入方塊、選項按鈕、單選下拉式清單方塊和多選核取方塊。	傳統、海洋藍和岩灰。
Multi-Factor Authentication	在此頁面上，使用者可以在註冊或登入期間驗證其電話號碼 (藉由使用文字或語音)。	傳統、海洋藍和岩灰。
錯誤	在發生例外狀況或錯誤時，系統會顯示此頁面。	傳統、海洋藍和岩灰。

裝載頁面內容

使用自己的 HTML 與 CSS 檔案自訂 UI 時，可以將 UI 內容裝載於支援 CORS 的任一公開供使用的 HTTPS 端點上。例如，Azure Blob 儲存體、Azure App Service、網頁伺服器、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 不支援 frame、iframe 或 form HTML 元素。

當地語系化內容

您可以在 Azure AD B2C 租用戶上啟用語言自訂，以將 HTML 內容當地語系化。啟用此項功能，可以允許 Azure AD B2C 設定 HTML 網頁的語言屬性，並會將 OpenID Connect 參數 ui_locales 傳遞至您的端點。

單一範本方法

在載入頁面期間，Azure AD B2C 會將 HTML 網頁的語言屬性，設定為目前的語言。例如： <html lang="en"> 。若要依據目前的語言呈現不同的樣式，使用 CSS :lang 選取器時可搭配 CSS 定義一併使用。

以下範例定義下列類別：

imprint-en - 當目前的語言為英文時使用。
imprint-de - 當目前的語言為德文時使用。
imprint - 當目前的語言既非英文也非德文時，所使用的預設類別。

.imprint-en:lang(en),
.imprint-de:lang(de) {
    display: inherit !important;
}
.imprint {
    display: none;
}

視頁面語言之不同，會顯示或隱藏以下的 HTML 元素：

<a class="imprint imprint-en" href="Link EN">Imprint</a>
<a class="imprint imprint-de" href="Link DE">Impressum</a>

多重範本方法

語言自訂功能允許 Azure AD B2C 將 OpenID Connect 參數 ui_locales 傳遞至您的端點。內容伺服器可使用此參數來提供語言特定的 HTML 頁面。

注意

Azure AD B2C 不會將 OpenID Connect 參數 (例如 ui_locales) 傳遞至例外狀況頁面。

您可以根據所使用的地區設定，從不同的地方提取內容。在已啟用 CORS 的端點中，您可以針對特定語言設定主機內容的資料夾結構。如果您使用萬用字元值 {Culture:RFC5646}，則會呼叫正確的語言。

例如，您自訂頁面的 URI 可能類以如下：

https://contoso.blob.core.windows.net/{Culture:RFC5646}/myHTML/unified.html

您可以從以下提取內容，載入法文頁面：

https://contoso.blob.core.windows.net/fr/myHTML/unified.html

逐步解說自訂頁面內容

以下是流程概觀：

先準備一個可用來裝載自訂頁面內容的位置 (可公開存取且已啟用 CORS 的 HTTPS 端點)。
下載並自訂預設頁面內容檔案，例如 unified.html。
將自訂頁面內容發佈至可公開使用的 HTTPS 端點。
為您的 Web 應用程式設定跨原始來源資源分享 (CORS)。
將原則指向您的自訂原則內容 URI。

必要條件

建立使用者流程，讓使用者能夠註冊並登入您的應用程式。
註冊 Web 應用程式。

完成在 Active Directory B2C 中開始使用自訂原則中的步驟
註冊 Web 應用程式。

1. 建立 HTML 內容

建立在標題中含有您產品品牌名稱的自訂內容。

複製下列 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>
```
將複製的程式碼片段貼至文字編輯器中

使用 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 ;
}

將檔案另存新檔為 customize-ui.html。

注意

如果您使用 login.microsoftonline.com，HTML 表單元素將會因安全性限制而遭到移除。若想要在自訂的 HTML 內容中使用 HTML 表單元素，請使用 b2clogin.com。

2. 建立 Azure Blob 儲存體帳戶

在本文中，我們使用 Azure Blob 儲存體來裝載內容。您可以選擇在 Web 伺服器上裝載您的內容，但必須在 Web 伺服器上啟用 CORS。

注意

在 Azure AD B2C 租用戶中，無法佈建 Blob 儲存體。您必須在 Azure AD 租用戶中建立這項資源。

若要在 Blob 儲存體中裝載 HTML 內容，請執行下列步驟：

登入 Azure 入口網站。
請確定您使用的目錄中，有您的 Azure AD 租用戶，且有訂閱：
1. 選取入口網站工具列中的目錄 + 訂閱圖示。
2. 在 [入口網站設定] | [目錄 + 訂閱] 頁面中，在 [目錄名稱] 清單內找到 Azure AD 目錄，然後選取 [切換]。
在 Azure 入口網站中，搜尋並選取 [儲存體帳戶]
選取 [+ 建立] 。
選取儲存體帳戶的 [訂用帳戶]。
建立資源群組，或選取現有的資源群組。
為儲存體帳戶輸入不重複的儲存體帳戶名稱。
為儲存體帳戶選取地理性區域。
[效能] 可保持為 [標準]。
備援可以維持異地備援儲存體 (GRS)
選取 [審核 + 建立]，並等候數秒鐘待 Azure AD 執行驗證。
選取 [建立] 以建立儲存體帳戶。部署完成後，會自動開啟 [儲存體帳戶] 頁面，或請選取 [前往資源]。

2.1 建立容器

若要在 Blob 儲存體中建立公用容器，請執行下列步驟：

選取左側功能表中 [資料儲存體] 下的 [容器]。
選取 [+ 容器]。
為 [名稱]，輸入 root。名稱可以是您自選的名稱 (例如 contoso)，但為了簡化範例，我們以 root 做為名稱。
針對 [公用存取層級]，選取 Bold。
選取 [建立] 建立容器。
選取 root，開啟新的容器。

2.2 上傳自訂頁面內容檔案

選取 [上傳] 。
選取 [選取檔案] 旁的資料夾圖示。
瀏覽並選取 customize-ui.html 檔案，也就是稍早在 [頁面 UI 自訂] 區段中所建立的檔案。
如果要上傳至子資料夾，請展開 [進階]，並在 [上傳至資料夾] 中輸入資料夾名稱。
選取 [上傳] 。
選取您上傳的 customize-ui.html Blob。
選取 [URL] 文字方塊右側的複製到剪貼簿 圖示，將 URL 複製到剪貼簿中。
在網頁瀏覽器中，瀏覽至您複製的 URL，確認是否可以存取上傳的 Blob。如果無法存取，例如出現了 ResourceNotFound 錯誤，請確認容器的存取類型已設為 blob。

3. 設定 CORS

執行以下步驟，設定跨原始資源分享的 Blob 儲存體：

瀏覽至儲存體帳戶。
選取左側功能表 [設定] 下的 [資源分享 (CORS)]。
針對 [允許的來源]，輸入 https://your-tenant-name.b2clogin.com。將 your-tenant-name 取代為您的 Azure AD B2C 租用戶名稱。例如： https://fabrikam.b2clogin.com 。輸入租用戶名稱時，請全部使用小寫字母。
針對 [允許的方法]GET，選取和 OPTIONS。
針對 [允許的標頭]，輸入星號 (*)。
針對 [公開的標頭]，輸入星號 (*)。
針對 [最大壽命]，輸入 200。
在頁面上方選取 [儲存]。

3.1 測試 CORS

執行下列步驟，驗證您是否已就緒：

重複設定 CORS 的步驟。針對 [允許的來源]，輸入 https://www.test-cors.org
瀏覽至 http://test-cors.org
針對 [遠端 URL] 方塊，貼上您 HTML 檔案的 URL。例如， https://your-account.blob.core.windows.net/root/azure-ad-b2c/unified.html
選取 [傳送要求]。結果應該會是 XHR status: 200。如果您收到錯誤，請確定您的 CORS 設定正確無誤。您也可能需要清除瀏覽器快取，或按 Ctrl+Shift+P 來開啟 InPrivate 瀏覽工作階段。

深入了解如何建立和管理 Azure 儲存體帳戶。

4. 更新使用者流程

確定您使用的是包含您 Azure AD B2C 租用戶的目錄：
1. 選取入口網站工具列中的目錄 + 訂閱圖示。
2. 在 [入口網站設定] | [目錄 + 訂閱] 頁面上，在目錄名稱清單中找到 Azure AD B2C 目錄，然後選取 [切換]。
在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]。
選取左側功能表中的 [使用者流程]，然後選取 [B2C_1_signupsignin1] 使用者流程。
選取 [頁面配置]，然後對 [統一註冊或登入頁面] 下的 [使用自訂頁面內容]，選取 [是]。
在 [自訂頁面 URI] 中，輸入您先前記下的 custom-ui.html 檔案 URI。
在頁面上方選取 [儲存]。

5. 測試使用者流程

在 Azure AD B2C 租用戶中，選取 [使用者流程]，然後選取 B2C_1_signupsignin1 使用者流程。
從頁面頂端選取 [執行使用者流程]。
在右側窗格中，選取 [執行使用者流程] 按鈕。

您應該會看到類似下列範例的頁面，而頁面上的置中元素會以您所建立的 CSS 檔案為基礎：

Web browser showing sign up or sign in page with custom UI elements

4. 修改擴充檔案

若要設定 UI 自訂，請從基底檔案將 ContentDefinition 及其子元素，複製到擴充檔案。

開啟原則的基底檔案。例如： SocialAndLocalAccounts/TrustFrameworkBase.xml 。此基底檔案是內含於自訂原則入門套件中的一個原則檔案，您應該可以在必要條件 (開始使用自訂原則) 中找到該檔案。
搜尋 ContentDefinitions 元素的完整內容並且複製。
開啟擴充檔案。例如 TrustFrameworkExtensions.xml。搜尋 BuildingBlocks 元素。如果此元素不存在，請加以新增。
貼上您複製的 ContentDefinitions 元素完整內容，作為 BuildingBlocks 元素的子項目。
在您複製的 XML 中，搜尋包含 Id="api.signuporsignin" 的 ContentDefinition 元素。

將 LoadUri 的值變更為您上傳至儲存體的 HTML 檔案 URL。例如： https://your-storage-account.blob.core.windows.net/your-container/customize-ui.html 。

自訂原則應類似以下程式碼片段：

<BuildingBlocks>
  <ContentDefinitions>
    <ContentDefinition Id="api.signuporsignin">
      <LoadUri>https://your-storage-account.blob.core.windows.net/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>

儲存擴充檔案。

5. 上傳並測試更新後的自訂原則

5.1 上傳自訂原則

確定您使用的目錄包含您的 Azure AD B2C 租用戶。選取入口網站工具列中的 [目錄 + 訂用帳戶] 圖示。
在 [入口網站設定] | [目錄 + 訂用帳戶] 頁面上，在 [目錄名稱] 清單中尋找您的 Azure AD B2C 目錄，然後選取 [切換]。
搜尋並選取 [Azure AD B2C]。
在 [原則] 之下，選取 [Identity Experience Framework]。
選取 [上傳自訂原則]。
上傳您先前變更的擴充檔案。

5.2 使用 [立即執行] 測試自訂原則

選取您上傳的原則，然後選取 [立即執行]。
您應該可以使用電子郵件地址註冊。

設定動態自訂頁面內容的 URI

使用 Azure AD B2C 自訂原則，可以在 URL 路徑或查詢字串中傳送參數。將參數傳遞至您的 HTML 端點，即可動態變更網頁內容。例如，視您從 Web 或行動裝置應用程式傳遞的參數而定，您可以變更 Azure AD B2C 註冊或登入背景影像。參數可以是任何宣告解析器，像是應用程式識別碼、語言識別碼，或是自訂查詢字串參數，例如 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>.azurewebsites.net/home/unified。您的自訂原則 ContentDefinition 應類似以下程式碼片段：

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

當 Azure AD B2C 載入頁面時，會呼叫您的 Web 伺服器端點：

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

動態頁面內容 URI

視所使用參數的不同，從不同位置提取內容。在已啟用 CORS 的端點中，設定要用來裝載內容的資料夾結構。例如，可以使用以下的結構來整理內容。 Root 資料夾/各語言的資料夾/您的 HTML 檔案。例如，自訂頁面的 URI 可能類以如下：

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

Azure AD B2C 會傳送語言的兩個字母 ISO 代碼；例如，fr 代表法文：

https://contoso.blob.core.windows.net/fr/myHTML/unified.html

範例範本

您可以在此找到 UI 自訂的範例範本：

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

此專案包含下列範本：

若要使用範例：

複製本機電腦的存放庫。選擇範本資料夾 /AzureBlue、/MSA 或 /classic。
依照先前章節所述，將範本資料夾和 /src 資料夾下的所有檔案，上傳至 Blob 儲存體。
接著，開啟範本資料夾中的每一個 \*.html 檔案。然後，將 URL 的所有執行個體 https://login.microsoftonline.com 以步驟 2 中所上傳的 URL 取代。例如：

寄件者:
```
https://login.microsoftonline.com/templates/src/fonts/segoeui.WOFF
```
變更為：
```
https://your-storage-account.blob.core.windows.net/your-container/templates/src/fonts/segoeui.WOFF
```
儲存 \*.html 檔案，然後上傳至 Blob 儲存體。
現在要修改原則，請依照先前所述，指向您的 HTML 檔案。
如果發現有遺漏的字型、影像或 CSS 的情況，請檢查延伸模組原則和 \*.html 檔案中的參照。

在自訂 HTML 中使用公司商標資產

若要在自訂 HTML 中使用公司商標資產，請在 <div id="api"> 標記之外加入以下標記。該影像來源隨後就會以背景影像與橫幅標誌加以取代。

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

後續步驟

了解如何啟用用戶端 JavaScript 程式碼。