在 Azure Active Directory B2C 中,使用 HTML 範本自訂使用者介面
開始之前,請使用 [選擇原則類型] 選取器,選擇您要設定的原則類型。 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)。
您的自訂頁面內容可以包含任何 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 應用程式。
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 租用戶,且有訂閱:
- 選取入口網站工具列中的目錄 + 訂閱圖示。
- 在 [入口網站設定] | [目錄 + 訂閱] 頁面中,在 [目錄名稱] 清單內找到 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 租用戶的目錄:
- 選取入口網站工具列中的目錄 + 訂閱圖示。
- 在 [入口網站設定] | [目錄 + 訂 閱] 頁面上,在目錄名稱清單中找到 Azure AD B2C 目錄,然後選取 [切換]。
- 在 Azure 入口網站中,搜尋並選取 [Azure AD B2C]。
- 選取左側功能表中的 [使用者流程],然後選取 [B2C_1_signupsignin1] 使用者流程。
- 選取 [頁面配置],然後對 [統一註冊或登入頁面] 下的 [使用自訂頁面內容],選取 [是]。
- 在 [自訂頁面 URI] 中,輸入您先前記下的 custom-ui.html 檔案 URI。
- 在頁面上方選取 [儲存]。
5. 測試使用者流程
- 在 Azure AD B2C 租用戶中,選取 [使用者流程],然後選取 B2C_1_signupsignin1 使用者流程。
- 從頁面頂端選取 [執行使用者流程]。
- 在右側窗格中,選取 [執行使用者流程] 按鈕。
您應該會看到類似下列範例的頁面,而頁面上的置中元素會以您所建立的 CSS 檔案為基礎:
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 程式碼。