Keycloak Theme Development

Keycloak is the default OIDC provider for Thunderbird Account. While we use a staging instance under the tbpro-dev realm for other projects, we spin up a keycloak docker container for theme development in this project.

You can find the contents of the keycloak theme ‘tbpro’ under

thunderbird-accounts
└── keycloak
└── themes
└── tbpro


Accessing template variables

Since Keycloak uses traditional server-side rendered templates any accessible template variables are normally loaded into window._page for template level variables and window._page.currentView for any page specific variables. Localization information can be retrieved from a flat window._l10n.

Keycloak uses freemarker templates. If you need to hook up any of the template variables you can do so in template.ftl or the specific page’s template. A good example of this is login.ftl where we append additional variables to window._page.currentView. Annoyingly these variables are expressed in a similar way to es6 template literals. Be extra careful not to attempt to use them as such with the backtick character!

If you’re missing a variable you can generally find it on the original template (under the base theme) or via the template provider located here.

Adjusting l10n

Localization can be modified via the messages_<locale>.properties file located under

thunderbird-accounts
└── keycloak
└── themes
└── tbpro
└── theme type (e.g. login, email, etc…)
└── messages

If you add new localization you’ll need to adjust the window._l10n variable in template.ftl

l10n pain points

Since we’re essentially piping strings from one localization system to another there’s some quirks you should be aware of.

  • Avoid using single quotes: '' as it can cause rendering problems. Instead use this character: ’.

  • Ensure you save the message properties file as UTF-8. Some editors don’t do this.

  • If you need to use a special character defined in vue-i18n you’ll need to specify the linear interpolation via a .replaceAll. (e.g. @thundermail.com".replace('@', "{'@'}").) Using curly braces will trip up keycloak’s template rendering.