Keycloak is an open-source identity and access management solution aimed at modern applications and services. It provides comprehensive features to handle user authentication, authorization, and management. Customizing themes in Keycloak enables you to personalize the look of the login pages, emails, and other user-facing elements. Keycloak themes consist of FreeMarker templates, CSS, and JavaScript files, as well as properties to define specific aspects of the appearance and behavior.
Here are the main steps to create a custom theme:
Locate Keycloak Themes Directory Keycloak themes are stored in the themes directory of the Keycloak installation.
<root-directory>/themes/
Create a New Theme Folder Inside the themes directory, create a new folder for your custom theme.
<root-directory>/themes/custom-theme
Theme Types Keycloak supports different types of themes, each of which has its subfolder inside your custom theme folder:
Login
: Customize the login and registration pages.
Account
: Customize the user account management pages.
Admin
: Customize the Keycloak Admin Console.
Email
: Customize the email templates.
Create subdirectories in your theme folder for each type you want to customize.
For example:
<root-directory>/themes/custom-theme/login
<root-directory>/themes/custom-theme/account
<root-directory>/themes/custom-theme/admin
<root-directory>/themes/custom-theme/email
You can now modify the files in this folder to adjust the appearance. 4. Customize FreeMarker Templates Customise the FreeMarker (.ftl) templates, based on needs.
Customize CSS Customize the CSS by creating or modifying the theme.properties file in your theme’s directory. Define your custom styles in a new CSS file and reference it in theme.properties. For example, add the following in theme.properties
styles=my-style.css
Then, create my-style.css in the corresponding directory:
<root-directory>/themes/custom-theme/login/resources/css/my-style.css
Add Custom Images/Resources
Place custom images, fonts, or other resources in the resources
folder of your theme directory.
For example:
<root-directory>/themes/custom-theme/login/resources/img/logo.png
Modify Theme Properties
Each theme can have a theme.properties
file where you define various configuration options, like the parent theme, internationalization settings, and resources.
Example theme.properties
parent=base
styles=my-style.css
Configure the Theme in Keycloak Admin Console After creating the theme, you need to apply it:
When creating email templates, several common issues can arise that affect design, functionality, and user experience. Different email clients often render HTML and CSS inconsistently, leading to broken layouts and formatting issues, especially when lacking mobile responsiveness. Images may be blocked or slow to load, and unsupported fonts or styles can create inconsistencies. Ensuring accessibility is crucial, including adding alt text for images and using readable fonts. Testing is essential across platforms to avoid broken links, images, or layouts.
"This blog will help you avoid the issues mentioned above."
Create the email
directory under your customised theme
<KEYCLOAK_HOME>/themes/<your_theme_name>/email
Within the email directory create theme.properties
files and define the parent theme.
Example:
parent=keycloak
Create 2 more subdirectories html & text
Create the HTML
email templates using FTL
syntax in the HTML
directory.
Create the plain text
email templates in the text
directory. These templates provide a fallback for clients that do not render HTML emails.
HTML Template Using FTL syntax
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Email Verification</title>
</head>
<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f9f9f9;">
<table width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color: #f9f9f9; width: 100%; margin: 0; padding: 0;">
<tr>
<td align="center" style="padding: 20px 0;">
<table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: #ffffff; border: 1px solid #ddd; width: 100%; max-width: 600px;">
<tr>
<td style="padding: 20px; text-align: center;">
<img src="https://www.example.com/logo.png" alt="Company Logo" style="width: 100px; height: auto;">
</td>
</tr>
<tr>
<td style="padding: 20px; font-size: 16px; color: #333;">
<h1 style="font-size: 24px; color: #333; margin: 0 0 20px;">Hello ${user.firstName},</h1>
<p style="margin: 0 0 20px;">Please verify your email address by clicking the link below:</p>
<p style="margin: 0 0 20px;">
<a href="${link}" style="color: #007bff; text-decoration: none; display: inline-block; padding: 10px 20px; border: 1px solid #007bff; border-radius: 5px;">
Verify Email
</a>
</p>
<p style="margin: 0 20px;">If you did not request this verification, please ignore this email.</p>
<p style="margin: 0;">Thank you,<br>Your Company</p>
</td>
</tr>
<tr>
<td style="padding: 20px; text-align: center; font-size: 12px; color: #777;">
<p style="margin: 0;">© 2024 Your Company. All rights reserved.</p>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
</html>
Plain text email
Hello ${user.firstName},
Please verify your email address by clicking the link below:
${link}
If you did not request this verification, please ignore this email.
Thank you
Login to the Keycloak admin console. Navigate to Realm settings -> Themes
. Set the email theme to your customised theme.
Test your customized email template by triggering any email events.
Additional Tips
Dynamic Content
: Use FreeMarker variables (${user.firstName}, ${link}, etc.) to dynamically insert user-specific information into your email templates.Localization
: Keycloak supports localization of email templates. Language-specific property files can be created under the message directory (e.g., messages_en.properties for English).
Many modern HTML5 features
may not be fully supported by email clients, so it's best to use basic HTML elements for better compatibility.
Embedding videos or audio files
are typically not supported in email clients, so it is recommended to use links to external media instead.
Avoid using JavaScript, interactive HTML elements like <input>, <button>, or <form>
as they are often not supported by email clients.
Gmail has strict rules for rendering emails, and Base64-encoded images
(data:image/...) are not supported in Gmail for security and performance reasons.
Use inline CSS styles rather than embedded or external stylesheets. Many email clients strip out <style>
tags and linked stylesheets.
Certain CSS properties and selectors are not supported or are inconsistently supported across email clients. Avoid using:
:nth-child, :last-child
)::before, ::after
)float
, and display: flex
Media queries
are inconsistently supported, particularly in desktop email clients. They are more effective in mobile email clients but should be used with caution.
CSS animations and transitions
are typically unsupported in email templates and should be avoided.
Web fonts (@font-face
) are not widely supported. Stick to web-safe fonts like Arial, Helvetica, Times New Roman, etc.
By carefully following these steps and adhering to the outlined limitations, you will be able to proficiently craft and tailor an email theme in Keycloak. This will guarantee that your email communications seamlessly reflect your organization’s branding and deliver a consistent and polished user experience. This is applicable until Keycloak 26.0.6 (latest)
.
https://www.keycloak.org/docs/latest/server_admin/index.html