在 Azure Active Directory B2C 中使用 HTML 範本自定義使用者介面

2025-05-05

這很重要

自 2025 年 5 月 1 日起，Azure AD B2C 將不再可供新客戶購買。在我們的常見問題中深入瞭解。

開始之前，請使用此頁面頂端的 [選擇原則類型] 選取器，選擇您要設定的原則類型。 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 片段合併，然後向客戶顯示頁面。

自定義頁面內容邊界

自訂 HTML 頁面內容

使用您自己的商標建立 HTML 頁面，以提供您的自定義頁面內容。此頁面可以是靜態 *.html 頁面，或動態頁面，例如 .NET、Node.js或 PHP，不過，Azure B2C 不支援任何檢視引擎。動態頁面的任何伺服器端轉譯都必須由專用 Web 應用程式執行。

您的自定義頁面內容可以包含任何 HTML 元素，包括 CSS 和 JavaScript，但不能包含不安全的元素，例如 iframe。唯一必要的元素是設定為 idapi 的 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帳戶或本機帳戶。	經典、海洋藍和石板灰色。
登入（僅限）	登入頁面也稱為識別提供者選擇。它會使用本機帳戶或聯邦身份提供者來處理使用者登入。使用此頁面來允許登入，而不需要註冊。例如，在使用者能編輯其個人資料之前。	經典、海洋藍和石板灰色。
Self-Asserted	Azure AD B2C 中大部分的互動都是使用者自我聲明的，並且預期使用者提供輸入。例如，註冊頁面、登入頁面或密碼重設頁面。使用此範本作為社交帳戶註冊頁面、本機帳戶註冊頁面、本機帳戶登入頁面、密碼重設、編輯配置檔、封鎖頁面等的自定義頁面內容。自我判斷頁面可以包含各種輸入控件，例如：文字輸入方塊、密碼輸入方塊、單選按鈕、單選下拉式方塊，以及多重選取複選框。	經典、海洋藍和石板灰色。
多重因素驗證	在此頁面上，用戶可以在註冊或登入期間驗證其電話號碼（使用文字或語音）。	經典、海洋藍和石板灰色。
錯誤	發生例外狀況或錯誤時，會顯示此頁面。	經典、海洋藍和石板灰色。

裝載頁面內容

使用您自己的 HTML 和 CSS 檔案來自定義 UI 時，請在任何支援 CORS 的公開可用 HTTPS 端點上裝載您的 UI 內容。例如， Azure Blob 記憶體、 Azure App Services、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 不支援 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 中的自定義原則中的步驟。本教學課程會引導您更新自定義原則檔案，以使用您的 Azure AD B2C 租用戶設定。
註冊 Web 應用程式。

1.建立 HTML 內容

在標題中建立具有您產品品牌名稱的自定義頁面內容。

複製下列 HTML 代碼段。它是格式正確的 HTML5，其具有名為 <div id="api"></div> 的空白元素，其位於<body> 標籤內。這個元素表示要插入 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 記憶體來裝載我們的內容。您可以選擇在網頁伺服器上裝載內容，但必須在網頁伺服器上啟用 CORS。

備註

在 Azure AD B2C 租使用者中，您無法布建 Blob 記憶體。您必須在 Microsoft Entra 租戶中建立此資源。

若要在 Blob 記憶體中裝載 HTML 內容，請使用下列步驟：

登入 Azure 入口網站。
如果您有多個租戶的存取權，請選取頂端功能表中的設定圖示，從目錄 + 訂用帳戶功能表切換至Microsoft Entra ID 租戶。
在 Azure 入口網站中，搜尋並選取 [記憶體帳戶]
選取 + 建立。
請選擇你的儲存體帳戶的訂閱。
建立資源群組或選取現有的 資源群組 。
輸入儲存帳戶的唯一 儲存體帳戶名稱 。
選取記憶體帳戶的地理區域。
效能可以維持 在標準狀態。
備援可以保留 異地備援記憶體（GRS）
選取 [檢閱 + 建立 ]，然後等候幾秒鐘，Microsoft Entra ID 執行驗證。
選取 [建立] 以建立儲存體帳戶。部署完成後，記憶體帳戶頁面會自動開啟，或您需要選取 [移至資源]。

2.1 建立容器

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

在最左邊功能表中的 [ 設定 ] 下，選取 [ 組態]。
啟用 [允許 Blob 匿名存取]。
選取 [儲存]。
在左側功能表中 的 [數據記憶體 ] 下，選取 [ 容器]。
請選擇+ 容器。
針對 [名稱]，輸入 root。此名稱可以是您選擇的名稱，例如 contoso，但為了簡單起見，我們在此範例中使用 root 。
針對 公用存取層級，選取 Blob。選取 [Blob] 選項，即可允許此容器的匿名公用只讀存取。
選取建立以建立容器。
選取 root 以開啟新的容器。

2.2 上傳您的自定義頁面內容檔案

選取上傳。
選取 [ 選取檔案] 旁的資料夾圖示。
流覽至您稍早在 [頁面 UI 自定義] 區段中建立的 customize-ui.html，然後選取它。
如果您想要上傳至子資料夾，請展開 [ 進階 ]，然後在 [ 上傳至資料夾] 中輸入資料夾名稱。
選取上傳。
選取您上傳的 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
瀏覽至 www.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 來清除瀏覽器快取或開啟私人瀏覽會話。

深入瞭解如何建立和管理 Azure 記憶體帳戶。

4.更新使用者流程

如果您有多個租用戶的存取權，請使用頂端功能表中的 [設定] 圖示，從 [目錄 + 訂用帳戶] 功能表切換至您的 Azure AD B2C 租用戶。
在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]。
在左側功能表中，選擇使用者流程，然後選擇B2C_1_signupsignin1使用者流程。
選取 [版面配置]，然後在 [統一註冊或登入] 頁面底下，選取 [是] 以使用自定義頁面內容。
在 [自定義頁面 URI] 中，輸入您稍早記錄 custom-ui.html 檔案的 URI。
在頁面頂端，選取 [儲存]。

5.測試使用者流程

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

您應該會看到類似下列範例的頁面，其中的元素是根據您建立的 CSS 檔案置中的。

顯示使用自定義 UI 元素註冊或登入頁面的網頁瀏覽器

4.修改擴展名檔案

若要設定 UI 自定義，請將 ContentDefinition 及其子元素從基底檔案複製到延伸模組檔案：

開啟原則的基底檔案。例如： SocialAndLocalAccounts/TrustFrameworkBase.xml 。此基底檔案是自定義原則入門套件中包含的其中一個原則檔案，您應該已在必要條件中取得此檔案：開始使用自定義原則。
搜尋並複製 ContentDefinitions 元素的整個內容。
開啟延伸模組檔案。例如， TrustFrameworkExtensions.xml。搜尋 BuildingBlocks 元素。如果元素不存在，加以新增。
貼上您複製為 BuildingBlocks 元素子系之 ContentDefinitions 元素的整個內容。
搜尋您所複製的 XML 中包含的 Id="api.signuporsignin" 元素。

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

儲存延伸模組檔案。
啟用 JavaScript

5.上傳及測試已更新的自定義原則

5.1 上傳自定義原則

如果您有多個租用戶的存取權，請使用頂端功能表中的 [設定] 圖示，從 [目錄 + 訂用帳戶] 功能表切換至您的 Azure AD B2C 租用戶。
搜尋並選取 Azure AD B2C。
在 [ 原則] 底下，選取 [ 身分識別體驗架構]。
選取 上傳自定義政策。
上傳您先前變更的擴展名檔案。

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=00001111-aaaa-2222-bbbb-3333cccc4444

動態頁面內容 URI

您可以根據所使用的參數，從不同位置提取內容。在啟用 CORS 的端點中，設定資料夾結構來裝載內容。例如，您可以在下列結構中組織內容。 根資料夾/每個語言的資料夾/您的 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 檔案。然後將所有出現的 https://login.microsoftonline.com URL 替換為您在步驟 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 程式代碼。