Added documentation for themes
This commit is contained in:
Stian Thorgersen
parent
a667d0c5f5
commit
1d403c6f3f
4 changed files with 187 additions and 4 deletions
|
|
@ -13,6 +13,7 @@
|
|||
<!ENTITY SocialGoogle SYSTEM "modules/social-google.xml">
|
||||
<!ENTITY SocialTwitter SYSTEM "modules/social-twitter.xml">
|
||||
<!ENTITY SocialProviderSPI SYSTEM "modules/social-spi.xml">
|
||||
<!ENTITY Themes SYSTEM "modules/themes.xml">
|
||||
<!ENTITY Email SYSTEM "modules/email.xml">
|
||||
]>
|
||||
|
||||
|
|
@ -77,6 +78,8 @@
|
|||
&SocialProviderSPI;
|
||||
</chapter>
|
||||
|
||||
&Themes;
|
||||
|
||||
<chapter>
|
||||
<title>Email</title>
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -1,11 +1,12 @@
|
|||
<section id="social-spi">
|
||||
<title>Social Provider SPI</title>
|
||||
<para>
|
||||
Keycloak provides an SPI to make it easy to add additional social providers. This is done by implementing the
|
||||
<ulink url="https://raw.github.com/keycloak/keycloak/master/social/core/src/main/java/org/keycloak/social/SocialProvider.java">SocialProvider</ulink>
|
||||
interface and providing a provider configuration file (<literal>META-INF/services/org.keycloak.social.SocialProvider</literal>).
|
||||
Keycloak provides an SPI to make it easy to add additional social providers. This is done by implementing
|
||||
<literal>org.keycloak.social.SocialProvider</literal> in <literal>social/core</literal>
|
||||
and adding a provider configuration file (<literal>META-INF/services/org.keycloak.social.SocialProvider</literal>).
|
||||
</para>
|
||||
<para>
|
||||
A good reference for implementing a Social Provider is the <ulink url="https://github.com/keycloak/keycloak/tree/master/social/google">Google provider</ulink>.
|
||||
A good reference for implementing a Social Provider is the Google provider which you can find in <literal>social/google</literal>
|
||||
on GitHub or in the source download.
|
||||
</para>
|
||||
</section>
|
||||
163
docbook/reference/en/en-US/modules/themes.xml
Normal file
163
docbook/reference/en/en-US/modules/themes.xml
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
<chapter id="themes">
|
||||
<title>Themes</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<section>
|
||||
<title>Configure theme</title>
|
||||
<para>
|
||||
To configure the theme used by a realm open the <literal>Keycloak Admin Console</literal>, select your realm
|
||||
from the drop-down box in the top left corner. In the <literal>Optional Settings</literal> use the drop-down
|
||||
boxes for <literal>Login Theme</literal> and <literal>Account Theme</literal> to select the theme used
|
||||
by login forms and account management pages.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Creating a theme</title>
|
||||
<para>
|
||||
There are two types of themes in Keycloak, login and account. Login themes are used to customize the
|
||||
login forms, while account themes are used to customize account management. A theme consists of:
|
||||
<itemizedlist>
|
||||
<listitem><para>FreeMarker templates</para></listitem>
|
||||
<listitem><para>Stylesheets</para></listitem>
|
||||
<listitem><para>Scripts</para></listitem>
|
||||
<listitem><para>Images</para></listitem>
|
||||
<listitem><para>Message bundles</para></listitem>
|
||||
<listitem><para>Theme properties</para></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. It should be possible to achieve the customization required by styling these
|
||||
templates.
|
||||
</para>
|
||||
<para>
|
||||
To create a new theme, create a folder in <literal>.../standalone/configuration/themes/login</literal> or
|
||||
<literal>.../standalone/configuration/themes/account</literal>. The name of the folder is the name of the theme.
|
||||
Then create a file <literal>theme.properties</literal> inside the theme folder. The contents of the file should be:
|
||||
</para>
|
||||
<programlisting>parent=base</programlisting>
|
||||
<para>
|
||||
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.</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>
|
||||
</section>
|
||||
<section>
|
||||
<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. 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
|
||||
<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>
|
||||
</section>
|
||||
<section>
|
||||
<title>Templates</title>
|
||||
<para>
|
||||
For advanced use-cases where you need to modify the html structure it is also possible to override
|
||||
one or more of the templates. For example to override the login page create <literal>login.ftl</literal>
|
||||
inside your theme folder. The base templates all use <literal>template.ftl</literal> to create the
|
||||
basic structure of the page.
|
||||
</para>
|
||||
<para>
|
||||
The base templates are a good reference if you need to create your own templates, they can be
|
||||
found inside <literal>forms/common-themes/src/main/resources/theme</literal> on GitHub or in the source
|
||||
download.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>SPI</title>
|
||||
<para>
|
||||
For full control of login forms and account management Keycloak provides a number of SPIs.
|
||||
</para>
|
||||
<section>
|
||||
<title>Theme SPI</title>
|
||||
<para>
|
||||
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
|
||||
<literal>org.keycloak.freemarker.ThemeProvider</literal> and <literal>org.keycloak.freemarker.Theme</literal> in
|
||||
<literal>forms/common-freemarker</literal>.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
<literal>forms/common-themes</literal> on GitHub or the source download.
|
||||
</para>
|
||||
</section>
|
||||
<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.AccountProvider</literal>
|
||||
and <literal>org.keycloak.account.Account</literal> in <literal>forms/account-api</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Keycloaks default account management provider is built on the FreeMarker template engine (<literal>forms/account-freemarker</literal>).
|
||||
To make sure your provider is loaded you will either need to delete <literal>standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-account-freemarker-1.0-alpha-1.jar</literal>
|
||||
or disable it with the system property <literal>org.keycloak.account.freemarker.FreeMarkerAccountProvider</literal>.
|
||||
</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.LoginFormsProvider</literal>
|
||||
and <literal>org.keycloak.login.LoginForms</literal> in <literal>forms/login-api</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Keycloaks default login forms provider is built on the FreeMarker template engine (<literal>forms/login-freemarker</literal>).
|
||||
To make sure your provider is loaded you will either need to delete <literal>standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-login-freemarker-1.0-alpha-1.jar</literal>
|
||||
or disable it with the system property <literal>org.keycloak.login.freemarker.FreeMarkerLoginFormsProvider</literal>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
|
|
@ -25,6 +25,22 @@ When starting the server it can also import a realm from a json file:
|
|||
|
||||
mvn exec:java -Pkeycloak-server -Dimport=testrealm.json
|
||||
|
||||
### Live edit of html and styles
|
||||
|
||||
The Keycloak test server can load resources directly from the filesystem instead of the classpath. This allows editing html, styles and updating images without restarting the server. To make the server use resources from the filesystem start with:
|
||||
|
||||
mvn exec:java -Pkeycloak-server -Dresources
|
||||
|
||||
You can also specify the theme directory used by the server with:
|
||||
|
||||
mvn exec:java -Pkeycloak-server -Dkeycloak.theme.dir=<PATH TO THEMES DIR>
|
||||
|
||||
For example to use the example themes run the server with:
|
||||
|
||||
mvn exec:java -Pkeycloak-server -Dkeycloak.theme.dir=examples/themes
|
||||
|
||||
**NOTE:** If `keycloak.theme.dir` is specified the default themes (base, rcue and keycloak) are loaded from the classpath
|
||||
|
||||
TOTP codes
|
||||
----------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue