JBoss.orgCommunity Documentation
Keycloak provides theme support for login forms and account management. This allows customizing the look and feel of end-user facing pages so they can be integrated with your brand and applications.
To configure the theme used by a realm open the Keycloak Admin Console
, select your realm
from the drop-down box in the top left corner. In the Optional Settings
use the drop-down
boxes for Login Theme
and Account Theme
to select the theme used
by login forms and account management pages.
Keycloak comes bundled with default themes in standalone/configuration/themes
. It is
not recommended to edit these themes directly. Instead you should create a new theme to extend a default
theme. A good reference is to copy the keycloak themes as these extend the base theme to add styling.
There are several types of themes in Keycloak:
A theme consists of:
FreeMarker templates
Stylesheets
Scripts
Images
Message bundles
Theme properties
A theme can extend another theme. When extending a theme you can override individual files (templates, stylesheets, etc.). The recommended way to create a theme is to extend the base theme. The base theme provides templates and a default message bundle. It should be possible to achieve the customization required by styling these templates.
To create a new theme, create a folder in .../standalone/configuration/themes/< theme type>
.
The name of the folder is the name of the theme. Then create a file theme.properties
inside the theme folder.
The contents of the file should be:
parent=base
You have now created your theme. Check that it works by configuring it for a realm. It should look the same as the base theme as you've not added anything to it yet. The next sections will describe how to modify the theme.
A theme can have one or more stylesheets, to add a stylesheet create a file inside resources/css
(for example resources/css/styles.css
)
inside your theme folder. Then registering it in theme.properties
by adding:
styles=css/styles.css
The styles
property supports a space separated list so you can add as many
as you want. For example:
styles=css/styles.css css/more-styles.css
A theme can have one or more scripts, to add a script create a file inside resources/js
(for example resources/js/script.js
)
inside your theme folder. Then registering it in theme.properties
by adding:
scripts=js/script.js
The scripts
property supports a space separated list so you can add as many
as you want. For example:
scripts=js/script.js js/more-script.js
To make images available to the theme add them to resources/img
. They can then be used
through stylesheets. For example:
body { background-image: url('../img/image.jpg'); }
Or in templates, for example:
<img src="${url.resourcesPath}/img/image.jpg">
Text in the templates are loaded from message bundles. Currently internationalization isn't supported,
but that will be added in a later release. A theme that extends another theme will inherit all messages
from the parents message bundle, but can override individual messages. For example to replace
Username
on the login form with Your Username
create the file
messages/messages.properties
inside your theme folder and add the following content:
username=Your Username
Keycloak uses Freemarker Templates in order to generate HTML.
These templates are defined in .ftl
files and can be overriden from the base theme.
Check out the Freemarker website on how to form a template file.
For full control of login forms and account management Keycloak provides a number of SPIs.
The Theme SPI allows creating different mechanisms to providing themes for the default FreeMarker based
implementations of login forms and account management. To create a theme provider you will need to implement
org.keycloak.freemarker.ThemeProvider
and org.keycloak.freemarker.Theme
in
forms/common-freemarker
.
Keycloak comes with two theme providers, one that loads themes from the classpath (used by default themes)
and another that loads themes from a folder (used by custom themes). Looking at these
would be a good place to start to create your own theme provider. You can find them inside
forms/common-themes
on GitHub or the source download.
The Account SPI allows implementing the account management pages using whatever web framework or templating
engine you want. To create an Account provider implement org.keycloak.account.AccountProviderFactory
and org.keycloak.account.AccountProvider
in forms/account-api
.
Keycloaks default account management provider is built on the FreeMarker template engine (forms/account-freemarker
).
To make sure your provider is loaded you will either need to delete standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-account-freemarker-1.0-beta-3.jar
or disable it with the system property org.keycloak.account.freemarker.FreeMarkerAccountProviderFactory
.
The Login SPI allows implementing the login forms using whatever web framework or templating
engine you want. To create a Login forms provider implement org.keycloak.login.LoginFormsProviderFactory
and org.keycloak.login.LoginFormsProvider
in forms/login-api
.
Keycloaks default login forms provider is built on the FreeMarker template engine (forms/login-freemarker
).
To make sure your provider is loaded you will either need to delete standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-login-freemarker-1.0-beta-3.jar
or disable it with the system property org.keycloak.login.freemarker.FreeMarkerLoginFormsProviderFactory
.