Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/p2-inc/keycloak-themes

Themes and theme utilities meant for simple theme customization without deploying a packaged theme
https://github.com/p2-inc/keycloak-themes

Last synced: about 2 months ago
JSON representation

Themes and theme utilities meant for simple theme customization without deploying a packaged theme

Host: GitHub
URL: https://github.com/p2-inc/keycloak-themes
Owner: p2-inc
License: other
Created: 2022-10-17T18:53:35.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-04-29T16:08:01.000Z (2 months ago)
Last Synced: 2024-04-29T17:29:01.171Z (2 months ago)
Language: Mustache
Size: 695 KB
Stars: 22
Watchers: 2
Forks: 12
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: COPYING

Lists

awesome-keycloak - Extension for runtime loading of CSS themes
trackawesomelist - Extension for runtime loading of CSS themes (⭐24)

README

> :rocket: **Try it for free** in the new Phase Two [keycloak managed service](https://phasetwo.io/?utm_source=github&utm_medium=readme&utm_campaign=keycloak-themes). See the [announcement and demo video](https://phasetwo.io/blog/self-service/) for more information.

# keycloak-themes

Themes and theme utilities meant for simple theme customization without deploying a packaged theme.

- A modified login theme that allows colors, logo, CSS to be loaded from Realm attributes.
- An implementation of `ThemeProvider` that loads named Freemarker templates and messages from Realm attributes. Currently only for email.
- An implementation of `EmailTemplateProvider` that allows the use of mustache.js templates.

This extension is used in the [Phase Two](https://phasetwo.io) cloud offering, and is released here as part of its commitment to making its [core extensions](https://phasetwo.io/docs/introduction/open-source) open source. Please consult the [license](COPYING) for information regarding use.

## Quick start

The easiest way to get started is our [Docker image](https://quay.io/repository/phasetwo/phasetwo-keycloak?tab=tags). Documentation and examples for using it are in the [phasetwo-containers](https://github.com/p2-inc/phasetwo-containers) repo. The most recent version of this extension is included.

## Installation

If you wish to build this yourself, you can do so with a few simple steps:

1. Build the jar:
```
mvn clean install
```

2. Copy the jar produced in `target/` to your `providers` directory (for Quarkus) or `standalone/deployments` directory (for legacy) and rebuild/restart keycloak.

After #1, you can also run `docker-compose up` if you want to take a quick look.

## Overview

### Login theme

The login theme is named `attributes`. It assumes you will store the values as Realm attributes with the following keys:

- `_providerConfig.assets.login.css`: CSS you want to be loaded after the standard login.css
- `_providerConfig.assets.login.backgroundColor`: override for `--pf-global--primary-color--100`.
- `_providerConfig.assets.login.primaryColor`: override for `--pf-global--secondary-color--100`.
- `_providerConfig.assets.login.secondaryColor`: override for `--pf-global--BackgroundColor--100`.
- `_providerConfig.assets.logo.url`: URL of logo file that will be served as the `div.kc-logo-text.background-image`. Constrained to 150x150.
- `_providerConfig.assets.favicon.url`: URL of the favicon

#### Example CSS overrides

There are 3 examples of CSS themes that can be loaded using the property above. They are in the `examples/` directory. You can either set these as the `_providerConfig.assets.login.css` Realm attribute, or, if you are using the Phase Two admin console theme, set them in the **Styles** -> **Login** section.

* Consumer
* Enterprise
* SaaS

### Email theme

The custom `ThemeProvider` installs one email theme called `attributes` which allows you to override any .ftl template (from base) using Realm attributes with the following key format:
```
_providerConfig.theme.email.templates.
```

Messages can be overridden with the following key format:
```
_providerConfig.theme.email.messages.
```

You can also select a different base theme. To use that, set the following variable with the theme you want to override:
```
_providerConfig.theme.email.parent
```
Note that the current base theme is `mustache` which requires the use of the custom `EmailTemplateProvider` below. If you switch it back to `base` by setting the realm attribute, you can override the .ftl templates.

In order to run the email theme, you must turn theme caching off. This is because themes are cached in Keycloak with a common `KeycloakSession`, which will contain the incorrect Realm in the context for lookup of attributes. In practice, we have not noticed a significant performance impact of this. This requires setting the following command line flag for `start` or `start-dev`:
```
--spi-theme-cache-themes=false
```

### Mustache templates

The implementation of `EmailTemplateProvider` that allows the use of mustache.js templates will need to override the default implementation in Keycloak. This has to be specified as an SPI override at startup. If you want to use it, you will need to set the following command line flags for `start` or `start-dev`:
```
--spi-email-template-provider=freemarker-plus-mustache --spi-email-template-freemarker-plus-mustache-enabled=true
```

#### Notes
- For the underlying implementation, we use Sam Pullara's [mustache.java](https://github.com/spullara/mustache.java).

#### Issues
- We get equivalent funcationlity to the methods like `linkExpirationFormatter(linkExpiration)` by using the library's lambda functionality, and using the mustache-y syntax `{{#linkExpirationFormatter}}{{linkExpiration}}{{/linkExpirationFormatter}}`, but there isn't complete coverage yet.
- There is essentially no i18n at this point, so only the english templates work.

---