Obtain access token for user in the realm master with username admin and password password:

curl \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=password" \
  -d "grant_type=password" \
  "http://localhost:8080/auth/realms/master/protocol/openid-connect/token"

The result will be a JSON document. To invoke the API you need to extract the value of the access_token property. You can then invoke the API by including the value in the Authorization header of requests to the API.

The following example shows how to get the details of the master realm:

curl \
  -H "Authorization: bearer eyJhbGciOiJSUz..." \
  "http://localhost:8080/auth/admin/realms/master"

A theme can provide one or more types to customize different aspects of Red Hat Single Sign-On. The types available are:

All theme types, except welcome, is configured through the Admin Console. To change the theme used for a realm open the Admin Console, select your realm from the drop-down box in the top left corner. Under Realm Settings click on Themes.

To change the welcome theme you need to edit keycloak-server.json (in standalone/configuration or domain/servers/{server name}/configuration) and add welcomeTheme to the theme element, for example:

"theme": {
    ...
    "welcomeTheme": "custom-theme",
    ...
}

If the server is running you need to restart the server for the changes to the welcome theme to take effect.

Red Hat Single Sign-On comes bundled with default themes in the server’s root themes directory. To simplify upgrading you should not edit the bundled themes directly. Instead create your own theme that extends one of the bundle themes.

A theme consists of:

Unless you plan to replace every single page you should extend another theme. Most likely you will want to extend the Red Hat Single Sign-On theme, but you could also consider extending the base theme if you are significantly changing the look and feel of the pages. The base theme primarily consists of HTML templates and message bundles, while the Red Hat Single Sign-On theme primarily contains images and stylesheets.

When extending a theme you can override individual resources (templates, stylesheets, etc.). If you decide to override HTML templates bear in mind that you may need to update your custom template when upgrading to a new release.

While creating a theme it’s a good idea to disable caching as this makes it possible to edit theme resources directly from the themes directory without restarting Red Hat Single Sign-On. To do this edit standalone/configuration/keycloak-server.json for theme set staticMaxAge to -1 and both cacheTemplates and cacheThemes to false:

"theme": {
    ...
    "staticMaxAge": -1,
    "cacheTemplates": false,
    "cacheThemes": false,
    ...
}

Remember to re-enable caching in production as it will significantly impact performance.

To create a new theme start by creating a new directory in the themes directory. The name of the directory becomes the name of the theme. For example to create a theme called mytheme create the directory themes/mytheme.

Inside the theme directory create a directory for each of the types your theme is going to provide. For example to add the login type to the mytheme theme create the directory themes/mytheme/login.

For each type create a file theme.properties which allows setting some configuration for the theme. For example to configure the theme themes/mytheme/login that we just created to extend the base theme and import some common resources create the file themes/mytheme/login/theme.properties with following contents:

parent=base
import=common/keycloak

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 Themes. For Login Theme select mytheme and click Save. Then open the login page for the realm.

You can do this either by login through your application or by opening the Account Management console (/realms/{realm name}/account).

To see the effect of changing the parent theme, set parent=keycloak in theme.properties and refresh the login page.

.login-pf body {
    background: DimGrey none;
}

styles=css/styles.css

styles=lib/patternfly/css/patternfly.css lib/zocial/zocial.css css/login.css css/styles.css

alert('Hello');

scripts=js/script.js

body {
    background-image: url('../img/image.jpg');
    background-size: cover;
}

<img src="${url.resourcesPath}/img/image.jpg">

usernameOrEmail=Your Username

usernameOrEmail=Brukernavn
password=Passord

locales=en,no

locale_no=Norsk

<#import "template.ftl" as layout>
<h1>HELLO WORLD!</h1>
...

passwordResetSubject=My password recovery
passwordResetBody=Reset password link: {0}
passwordResetBodyHtml=<a href="{0}">Reset password</a>

Themes can be deployed to Red Hat Single Sign-On by copying the theme directory to themes or it can be deployed as an archive. During development copying the theme to the themes directory, but in production you may want to consider using an archive. An archive makes it simpler to have a versioned copy of the theme, especially when you have multiple instances of Red Hat Single Sign-On for example with clustering.

To deploy a theme as an archive you need to create a ZIP archive with the theme resources. You also need to add a file META-INF/keycloak-themes.json to the archive that lists the available themes in the archive as well as what types each theme provides.

For example for the mytheme theme create mytheme.zip with the contents:

The contents of META-INF/keycloak-themes.json in this case would be:

{
    "themes": [{
        "name" : "mytheme",
        "types": [ "login", "email" ]
    }]
}

A single archive can contain multiple themes and each theme can support one or more types.

The deploy the archive to Red Hat Single Sign-On you can either manually create a module in modules or use the jboss-cli command. It’s simplest to use jboss-cli as it creates the required directories and module descriptor for you.

To deploy mytheme.zip on Linux run:

bin/jboss-cli.sh --command="module add --name=org.example.mytheme --resources=mytheme.zip"

On Windows run:

bin\jboss-cli.bat --command="module add --name=org.example.mytheme --resources=mytheme.zip"

This command creates modules/org/example/mytheme/main directory with the mytheme.zip archive and module.xml.

To manually create the module create the directory modules/org/keycloak/example/mytheme/main, copy mytheme.zip to this directory and create the file modules/org/keycloak/example/mytheme/main/module.xml with the contents:

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="org.keycloak.example.themes">
    <resources>
        <resource-root path="mytheme.zip"/>
    </resources>
</module>

You also need to register the module with Red Hat Single Sign-On. This is done by editing keycloak-server.json (in standalone/configuration or domain/servers/{server name}/configuration) and adding the module to theme/module/modules. For example:

[
"theme": {
    ...
    "module": {
        "modules": [ "org.example.mytheme" ]
    }
}

If the server is running you need to restart the server after changing keycloak-server.json.

To be able to enter custom attributes in the registration page copy the template themes/base/login/register.ftl to the login type of your custom theme. Then open the copy in an editor.

As an example to add a mobile number to the registration page add the following snippet to the form:

<div class="form-group">
   <div class="${properties.kcLabelWrapperClass!}">
       <label for="user.attributes.mobile" class="${properties.kcLabelClass!}">Mobile number</label>
   </div>

   <div class="col-sm-10 col-md-10">
       <input type="text" class="${properties.kcInputClass!}"  id="user.attributes.mobile" name="user.attributes.mobile"/>
   </div>
</div>

To see the changes make sure your realm is using your custom theme for the login theme and open the registration page.

To be able to manage custom attributes in the user profile page in the account management console copy the template themes/base/account/account.flt to the account type of your custom theme. Then open the copy in an editor.

As an example to add a mobile number to the account page add the following snippet to the form:

<div class="form-group">
   <div class="col-sm-2 col-md-2">
       <label for="user.attributes.mobile" class="control-label">Mobile number</label>
   </div>

   <div class="col-sm-10 col-md-10">
       <input type="text" class="form-control" id="user.attributes.mobile" name="user.attributes.mobile" value="${(account.attributes.mobile!'')?html}"/>
   </div>
</div>

To see the changes make sure your realm is using your custom theme for the account theme and open the user profile page in the account management console.