Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Theming

Each SSO provider has its own way of customizing the log-in page, with different features and limitations. Learn how to customize the log-in page for different authentication providers.

Keycloak

Keycloak offers the most control over what can be customized, from the login page to the administration and user dashboards. SSO Kit offers a custom theme for Keycloak based on Lumo. It gives the provider’s login page a look and feel similar to what a Vaadin developer would experience using the Login component.

Installation

To use the Keycloak Lumo theme, you need to do a few things:

  1. First, download the sso-kit-keycloak-lumo JAR file from Maven.

  2. Next, copy the JAR file into the /providers directory of your Keycloak installation.

Once you’ve done that, you can either set the theme for all or some clients in a realm.

  • To set the theme for all clients, go to "Realm settings", "Themes". At the "Login theme" selector, choose sso-kit-keycloak-lumo.

  • To set the theme on a specific client, go to "Clients" and find the client. At the "Login settings" section, select sso-kit-keycloak-lumo as the "Login theme".

Customizing the Lumo Theme

You can also customize the Lumo theme to suit your application’s branding. To customize the theme, you need to do a couple of things:

  1. Create this directory structure under the /themes directory of your Keycloak installation:

    themes/
└── your-theme/
    ├── resources/css/
    │  └── my-theme-styles.css
    └── themes.properties

  2. In themes.properties, you need to define some properties such as the parent theme, and load the CSS files:

    # Specify the parent theme
parent=sso-kit-keycloak-lumo
# Need also to load the files from the parent theme
styles=css/lumo-common.css css/lumo-styles.css css/my-theme-styles.css

  3. Next, in my-theme-styles.css you can add your styles. For example, you might change the primary color to suit your application’s branding.

    html {
  --lumo-primary-color: rgb(22, 138, 72);
  --lumo-primary-color-50pct: rgba(22, 138, 72, 0.704);
}

While working on a custom theme, you might want to disable Keycloak theme caching. You would do that like this:

./bin/kc.bat start-dev --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false

For more instructions, see the official Keycloak theme documentation.