320 lines
16 KiB
XML
Executable file
320 lines
16 KiB
XML
Executable file
<!--
|
|
~ Copyright 2016 Red Hat, Inc. and/or its affiliates
|
|
~ and other contributors as indicated by the @author tags.
|
|
~
|
|
~ Licensed under the Apache License, Version 2.0 (the "License");
|
|
~ you may not use this file except in compliance with the License.
|
|
~ You may obtain a copy of the License at
|
|
~
|
|
~ http://www.apache.org/licenses/LICENSE-2.0
|
|
~
|
|
~ Unless required by applicable law or agreed to in writing, software
|
|
~ distributed under the License is distributed on an "AS IS" BASIS,
|
|
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
~ See the License for the specific language governing permissions and
|
|
~ limitations under the License.
|
|
-->
|
|
|
|
<chapter id="themes">
|
|
<title>Themes</title>
|
|
|
|
<para>
|
|
Keycloak provides theme support for web pages and emails. This allows customizing the look
|
|
and feel of end-user facing pages so they can be integrated with your applications.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Theme types</title>
|
|
<para>
|
|
A theme can support several types to customize different aspects of Keycloak. The types currently available
|
|
are:
|
|
<itemizedlist>
|
|
<listitem>Account - Account management</listitem>
|
|
<listitem>Admin - Admin console</listitem>
|
|
<listitem>Email - Emails</listitem>
|
|
<listitem>Login - Login forms</listitem>
|
|
<listitem>Welcome - Welcome pages</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Configure theme</title>
|
|
<para>
|
|
All theme types, except welcome, is configured through <literal>Keycloak Admin Console</literal>. To change
|
|
the theme used for a realm open the <literal>Keycloak Admin Console</literal>, select your realm
|
|
from the drop-down box in the top left corner. Under <literal>Settings</literal> click on <literal>Theme</literal>.
|
|
</para>
|
|
<para>
|
|
To set the theme for the <literal>master</literal> Keycloak admin console set the admin console theme for
|
|
the <literal>master</literal> realm. To set the theme for per realm admin access control set the admin console
|
|
theme for the corresponding realm.
|
|
</para>
|
|
<para>
|
|
To change the welcome theme you need to edit <literal>standalone/configuration/keycloak-server.json</literal>
|
|
and add <literal>welcomeTheme</literal> to the theme element, for example:
|
|
<programlisting>
|
|
"theme": {
|
|
...
|
|
"welcomeTheme": "custom-theme"
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Default themes</title>
|
|
<para>
|
|
Keycloak comes bundled with default themes in <literal>standalone/configuration/themes</literal>. You should
|
|
not edit the bundled themes directly. Instead create a new theme that extends a bundled theme.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Creating a theme</title>
|
|
<para>
|
|
A theme consists of:
|
|
<itemizedlist>
|
|
<listitem><ulink url="http://freemarker.org">FreeMarker</ulink> templates</listitem>
|
|
<listitem>Stylesheets</listitem>
|
|
<listitem>Scripts</listitem>
|
|
<listitem>Images</listitem>
|
|
<listitem>Message bundles</listitem>
|
|
<listitem>Theme properties</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
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. If you decide to override templates bear in mind that you may need to update
|
|
your templates when upgrading to a new release to include any changes made to the original template.
|
|
</para>
|
|
<para>
|
|
Before creating a theme it's a good idea to disable caching as this makes it possible to edit theme resources
|
|
without restarting the server. To do this open <literal>../standalone/configuration/keycloak-server.json</literal>
|
|
for <literal>theme</literal> set <literal>staticMaxAge</literal> to <literal>-1</literal> and
|
|
<literal>cacheTemplates</literal> and <literal>cacheThemes</literal> to <literal>false</literal>. For example:
|
|
<programlisting>[<![CDATA[
|
|
"theme": {
|
|
"default": "keycloak",
|
|
"staticMaxAge": -1,
|
|
"cacheTemplates": false,
|
|
"cacheThemes": false,
|
|
"folder": {
|
|
"dir": "${jboss.server.config.dir}/themes"
|
|
}
|
|
},
|
|
]]></programlisting>
|
|
Remember to re-enable caching in production as it will significantly impact performance.
|
|
</para>
|
|
<para>
|
|
To create a new theme create a directory for the theme in <literal>.../standalone/configuration/themes</literal>.
|
|
The name of the directory should be the name of the theme. For example to create a theme called <literal>example-theme</literal>
|
|
create the directory <literal>.../standalone/configuration/themes/example-theme</literal>. Inside the theme
|
|
directory you then need to create a directory for each of the types your theme is going to provide. For example
|
|
to add the login type to the <literal>example-theme</literal> theme create the directory
|
|
<literal>.../standalone/configuration/themes/example-theme/login</literal>.
|
|
</para>
|
|
<para>
|
|
For each type create a file <literal>theme.properties</literal> which allows setting some configuration for
|
|
the theme, for example what theme it overrides and if it should import any themes. For the above example we
|
|
want to override the base theme and import common resources from the Keycloak theme. To do this create the
|
|
file <literal>.../standalone/configuration/themes/example-theme/login/theme.properties</literal> with the
|
|
following contents:
|
|
<programlisting>[<![CDATA[
|
|
parent=base
|
|
import=common/keycloak
|
|
]]></programlisting>
|
|
</para>
|
|
<para>
|
|
You have now created a theme with support for the login type. To check that it works open the admin console.
|
|
Select your realm and click on <literal>Themes</literal>. For <literal>Login Theme</literal> select
|
|
<literal>example-theme</literal> and click <literal>Save</literal>. Then open the login page for the realm.
|
|
You can do this either by login through your application or by opening <literal>http://localhost:8080/realms/<realm name>/account</literal>.
|
|
</para>
|
|
<para>
|
|
To see the effect of changing the parent theme, set <literal>parent=keycloak</literal> in <literal>theme.properties</literal>
|
|
and refresh the login page. To follow the rest of the documentation set it back to <literal>parent=base</literal>
|
|
before continuing.
|
|
</para>
|
|
<section>
|
|
<title>Stylesheets</title>
|
|
<para>
|
|
A theme can have one or more stylesheets, to add a stylesheet create a file inside <literal>resources/css</literal>
|
|
(for example <literal>resources/css/styles.css</literal>) inside your theme folder. Then registering it
|
|
in <literal>theme.properties</literal> by adding:
|
|
</para>
|
|
<programlisting>styles=css/styles.css</programlisting>
|
|
<para>
|
|
The <literal>styles</literal> property supports a space separated list so you can add as many
|
|
as you want. For example:
|
|
</para>
|
|
<programlisting>styles=css/styles.css css/more-styles.css</programlisting>
|
|
For the example-theme above add <literal>example-theme/login/resources/css/styles.css</literal> with the
|
|
following content:
|
|
<programlisting>[<![CDATA[
|
|
#kc-form {
|
|
background-color: #000;
|
|
color: #fff;
|
|
padding: 20px;
|
|
}]]></programlisting>
|
|
Then edit <literal>example-theme/login/theme.properties</literal> and add <programlisting>styles=css/styles.css</programlisting>.
|
|
Refresh the login page to see your changes. It's not pretty, but you can see how easily you can modify the
|
|
styles for your theme.
|
|
</section>
|
|
<section>
|
|
<title>Scripts</title>
|
|
<para>
|
|
A theme can have one or more scripts, to add a script create a file inside <literal>resources/js</literal> (for example <literal>resources/js/script.js</literal>)
|
|
inside your theme folder. Then registering it in <literal>theme.properties</literal> by adding:
|
|
</para>
|
|
<programlisting>scripts=js/script.js</programlisting>
|
|
<para>
|
|
The <literal>scripts</literal> property supports a space separated list so you can add as many
|
|
as you want. For example:
|
|
</para>
|
|
<programlisting>scripts=js/script.js js/more-script.js</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>Images</title>
|
|
<para>
|
|
To make images available to the theme add them to <literal>resources/img</literal>. They can then be used
|
|
through stylesheets. For example:
|
|
</para>
|
|
<programlisting>body {
|
|
background-image: url('../img/image.jpg');
|
|
}</programlisting>
|
|
<para>
|
|
Or in templates, for example:
|
|
</para>
|
|
<programlisting><img src="${url.resourcesPath}/img/image.jpg"></programlisting>
|
|
</section>
|
|
<section>
|
|
<title>Messages</title>
|
|
<para>
|
|
Text in the templates are loaded from message bundles. A theme that extends another theme will inherit
|
|
all messages from the parents message bundle, but can override individual messages. For example to replace
|
|
<literal>Username</literal> on the login form with <literal>Your Username</literal> create the file
|
|
<literal>messages/messages.properties</literal> inside your theme folder and add the following content:
|
|
</para>
|
|
<programlisting>username=Your Username</programlisting>
|
|
<para>
|
|
For the admin console, there is a second resource bundle named <literal>admin-messages.properties</literal>.
|
|
This resource bundle is converted to JSON and shipped to the console to be processed by
|
|
angular-translate. It is found in the same directory as messages.properties and can be overridden
|
|
in the same way as described above.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Modifying HTML</title>
|
|
<para>
|
|
Keycloak uses <ulink url="http://freemarker.org">Freemarker Templates</ulink> in order to generate HTML.
|
|
These templates are defined in <literal>.ftl</literal> files and can be overriden from the base theme.
|
|
Check out the Freemarker website on how to form a template file. To override the login template for the
|
|
<literal>example-theme</literal> copy <literal>../standalone/configuration/themes/base/login/login.ftl</literal>
|
|
to <literal>../standalone/configuration/themes/example-theme/login</literal> and open it in an editor. After
|
|
the first line (<#import ...>) add <literal><h1>HELLO WORLD!</h1></literal> then refresh
|
|
the page.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Deploying themes</title>
|
|
<para>
|
|
Themes can be deployed to Keycloak by copying the theme directory to <literal>../standalone/configuration/themes</literal>
|
|
or it can be deployed as a module. For a single server or during development just copying the theme is fine, but
|
|
in a cluster or domain it's recommended to deploy as a module.
|
|
</para>
|
|
<para>
|
|
To deploy a theme as a module you need to create an jar (it's basically just a zip with jar extension) with
|
|
the theme resources and a file <literal>META/keycloak-themes.json</literal> that describes the themes contained
|
|
in the archive. For example <literal>example-theme.jar</literal> with the contents:
|
|
<itemizedlist>
|
|
<listitem>META-INF/keycloak-themes.json</listitem>
|
|
<listitem>theme/example-theme/login/theme.properties</listitem>
|
|
<listitem>theme/example-theme/login/login.ftl</listitem>
|
|
<listitem>theme/example-theme/login/resources/css/styles.css</listitem>
|
|
</itemizedlist>
|
|
The contents of META-INF/keycloak-themes.json in this case would be:
|
|
<programlisting>[<![CDATA[
|
|
{
|
|
"themes": [{
|
|
"name" : "example-theme",
|
|
"types": [ "login" ]
|
|
}]
|
|
}
|
|
]]></programlisting>
|
|
As you can see a single jar can contain multiple themes and each theme can support one or more types.
|
|
</para>
|
|
<para>
|
|
The deploy the jar as a module to Keycloak you can either manually create the module or use <literal>jboss-cli</literal>.
|
|
It's simplest to use <literal>jboss-cli</literal> as it creates the required directories and module descriptor
|
|
for you. To deploy the above jar <literal>jboss-cli</literal> run:
|
|
<programlisting>[<![CDATA[
|
|
KEYCLOAK_HOME/bin/jboss-cli.sh --command="module add --name=org.example.exampletheme --resources=example-theme.jar"
|
|
]]></programlisting>
|
|
If you're on windows run <programlisting>KEYCLOAK_HOME/bin/jboss-cli.bat</programlisting>.
|
|
</para>
|
|
<para>
|
|
This command creates <literal>modules/org/example/exampletheme/main</literal> containing <literal>example-theme.jar</literal>
|
|
and <literal>module.xml</literal>.
|
|
</para>
|
|
<para>
|
|
Once you've created the module you need to register it with Keycloak do this by editing
|
|
<literal>../standalone/configuration/keycloak-server.json</literal> and adding the module to <literal>theme/module/modules</literal>. For example:
|
|
<programlisting>[<![CDATA[
|
|
"theme": {
|
|
...
|
|
"module": {
|
|
"modules": [ "org.example.exampletheme" ]
|
|
}
|
|
}
|
|
]]></programlisting>
|
|
</para>
|
|
<para>
|
|
If a theme is deployed to <literal>../standalone/configuration/themes</literal> and as a module the first
|
|
is used.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>SPIs</title>
|
|
<para>
|
|
For full control of login forms and account management Keycloak provides a number of SPIs.
|
|
</para>
|
|
<section>
|
|
<title>Account SPI</title>
|
|
<para>
|
|
The Account SPI allows implementing the account management pages using whatever web framework or templating
|
|
engine you want. To create an Account provider implement <literal>org.keycloak.account.AccountProviderFactory</literal>
|
|
and <literal>org.keycloak.account.AccountProvider</literal>.
|
|
</para>
|
|
<para>
|
|
Once you have deployed your account provider to Keycloak you need to configure <literal>keycloak-server.json</literal> to specify which provider should be used:
|
|
<programlisting>
|
|
"account": {
|
|
"provider": "custom-provider"
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Login SPI</title>
|
|
<para>
|
|
The Login SPI allows implementing the login forms using whatever web framework or templating
|
|
engine you want. To create a Login forms provider implement <literal>org.keycloak.login.LoginFormsProviderFactory</literal>
|
|
and <literal>org.keycloak.login.LoginFormsProvider</literal> in <literal>forms/login-api</literal>.
|
|
</para>
|
|
<para>
|
|
Once you have deployed your account provider to Keycloak you need to configure <literal>keycloak-server.json</literal> to specify which provider should be used:
|
|
<programlisting>
|
|
"login": {
|
|
"provider": "custom-provider"
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|