keycloak 自定義登錄頁面詳細步驟如下:
因爲keycloak是jboss開發的,使用FTL後綴開發前端文件,可能根據以下方式實現
keycloak將前端頁面分爲四類:按類設置主題。
•Account - Account management
•Admin - Admin console
•Email - Emails
•Login - Login forms,包含註冊。
主題配置
可以爲不同的 Realm 分別設置主題,
進入keycloak管理控制檯,
選擇要配置主題的 Realm,
進入Realm Settings 頁面,
選擇 Themes 選項卡。
默認主題
keycloak默認提供了兩套主題,base 和 keycloak。
base是沒有加入任何樣式的。
keycloak加入了個性化的樣式。
並且 keycloak 主題繼承自 base 主題。
base主題登錄頁面:
keycloak主題登錄頁面:
創建自己的主題
一個主題由以下文件組成:
- HTML templates (Freemarker Templates)
- Images
- Message bundles -- 國際化使用
- Stylesheets
- Scripts
- Theme properties
新建主題,一般通過繼承base主題或者keycloak主題方式,而不是從零開始。
繼承一個主題後,可以重寫父主題的所有資源(templates、css、images...)
如果自定義主題重寫了父主題的template,那麼升級keycloak版本時,需要自己更新自定義主題的template。
新建自定義主題簡單步驟
1、在keycloak安裝目錄下的 themes 路徑下,新建文件夾,新建文件夾的名稱即新主題的名稱,如 mytheme。
2、在 mytheme 路徑下,按需爲四類頁面(account、admin、email、login)分別新建文件夾。
3、每個頁面類型下,分別創建 theme.properties 文件,在該配置文件中可以配置很多信息,如:繼承自哪個主題、導入common資源、引入哪些css、引入哪些js、以及其他一些配置信息。
4、驗證,自定義主題目錄新建完成後,登錄管理控制檯----Realm Settings----Themes,就可以選擇使用自己的主題了。
關於css
css放置路徑:
themes/自定義主題/頁面分類/resources/css/
如:mytheme主題的login頁面下新放入 style.css 文件:
themes/mytheme/login/resources/css/style.css
頁面中引入css文件方式:
方式一、
在 theme.properties文件中配置,如:
styles=css/stryles.css
如果要引入多個css文件,可以用空格分隔,如:
styles=lib/patternfly/css/patternfly.css lib/zocial/zocial.css css/login.css css/styles.css
在最終運行時的登錄頁面中,header 標籤中將會生成以下代碼:
上述方式,有一個特點需要注意,就是該頁面分類下的所有頁面都會引入這些css,如何給指定頁面引入css呢?參加下面的方式二。
方式二、
在 ftl 模板文件的頂部引入 css 文件,引入方式如下:
<link href="${url.resourcesPath}/css/ucloud.css" rel="stylesheet" />
關於 javascript
javascript放置路徑:
themes/自定義主題/頁面分類/resources/js/
如:mytheme主題的login頁面下新放入 javascript.js 文件:
themes/mytheme/login/resources/js/javascript.js
頁面中引入javascript文件方式:
方式一、
在 theme.properties文件中配置,如:
scripts=js/javascript.js
如果要引入多個javascript文件,可以用空格分隔,如:
scripts=js/javascript1.js js/javascript2.js
在最終運行時的登錄頁面中,header 標籤中將會生成以下代碼:
同 css ,上述方式,也有一個特點需要注意,就是該頁面分類下的所有頁面都會引入這些css,如何給指定頁面引入javascript呢?參加下面的方式二。
方式二、
在 ftl 模板文件的頂部引入 javascript 文件,引入方式如下:
<script src="${url.resourcesPath}/js/jquery.min.js" type="text/javascript"></script>
關於 images
圖片放置路徑:
themes/自定義主題/頁面分類/resources/img/
如:mytheme主題的login頁面下新放入image.jpg 文件:
themes/mytheme/login/resources/img/image.jpg
放入的圖片可以在 css 和 html 模板文件中使用。
css中使用方式
body {
background-image: url('../img/image.jpg');
background-size: cover;
}
html模板文件中使用方式
<img src="${url.resourcesPath}/img/image.jpg">
國際化 Messages
html模板文件中展示的所有文本信息都來自於 message bundles,
一個主題繼承自另外一個主題時,message bundle是會被一同繼承。
允許對繼承的message進行(部分或全部)重寫,如mytheme主題新建文件:\themes\mytheme\login\messages\messages_zh_CN.properties
內容如下:
# encoding: utf-8
invalidUserMessage=用戶名或密碼錯誤。
則登錄失敗提示信息將由原來的
“無效的用戶名或密碼。”
替換爲
“用戶名或密碼錯誤。”
關於message中佔位符
message.properties文件中,允許{0} {1}這種方式進行佔位,在使用時可以傳參。
如 message.properties中定義:
emailLinkIdp1=一封包含鏈接賬戶 {0} 和賬戶 {1} 到賬戶 {2} 的郵件已經發送到您的郵箱。
html模板中使用:
<p id="instruction1" class="instruction">
${msg("emailLinkIdp1", idpAlias, brokerContext.username, realm.displayName)}
</p>
Html模板
keycloak使用 Freemaker 模板來生成 html 文件,你可以重寫自己的模板。
關於 freemarker模板註釋符號:
<#-- --> 註釋的內容不會出現在最終生成的 html 文件中。
<!-- --> 註釋的內容會出現在最終生成的html文件,同 html 的註釋符 <!-- -->
freemaker模板中引用 theme.properties 中的配置
${properties.配置項名稱!}
不開啓主題緩存
開發自定義主題時,可以臨時禁用主題緩存,
禁用主題緩存後,修改主題資源後,不需要重啓keycloak,即可實時生效。
禁用主題緩存方法:
找到 standalone.xml 文件,找到 cacheThemes、cacheTemplate部分,配置如下:
<theme>
<staticMaxAge>-1</staticMaxAge>
<cacheThemes>false</cacheThemes>
<cacheTemplates>false</cacheTemplates>
...
</theme>
在生產環境,一定記得要開啓主題緩存,否則會很影響性能。
主題緩存默認是開啓的,默認配置如下:
<theme>
<staticMaxAge>2592000</staticMaxAge>
<cacheThemes>true</cacheThemes>
<cacheTemplates>true</cacheTemplates>
<dir>${jboss.home.dir}/themes</dir>
</theme>
學習FTL資料:https://blog.csdn.net/dengweilan/article/details/84840941