Mastering Keycloak: How to Build Custom Email Templates blog banner image

Mastering Keycloak: How to Build Custom Email Templates

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.

Creating a custom theme in Keycloak

Here are the main steps to create a custom theme:

  1. Locate Keycloak Themes Directory Keycloak themes are stored in the themes directory of the Keycloak installation.

    <root-directory>/themes/
  2. Create a New Theme Folder Inside the themes directory, create a new folder for your custom theme.

    <root-directory>/themes/custom-theme
  3. 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.

  • To customize the login theme, include login files (.ftl) in the login folder
  • To customize the email theme, include email files (.ftl) in the login folder
  1. 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
  2. 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
  3. 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
  4. Configure the Theme in Keycloak Admin Console After creating the theme, you need to apply it:

  • Log in to the Keycloak Admin Console.
  • Go to Realm Settings.
  • Under the Themes tab, choose your custom theme from the dropdown menus for Login Theme, Account Theme, Admin Console Theme, or Email Theme.

Common issues we may encounter in email templates

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."

Steps to Customize Email Templates in Keycloak

  1. Create the email directory under your customised theme

    <KEYCLOAK_HOME>/themes/<your_theme_name>/email
  2. Within the email directory create theme.properties files and define the parent theme. Example:

     parent=keycloak
  3. Create 2 more subdirectories html & text

    theme.properties

  4. Create the HTML email templates using FTL syntax in the HTML directory.

  5. 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;">&copy; 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
  6. Login to the Keycloak admin console. Navigate to Realm settings -> Themes. Set the email theme to your customised theme.

  7. 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).

Keycloak Email Template Limitations

HTML Limitations

  • 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.

CSS Limitations

  • 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:

    • Advanced selectors (e.g., :nth-child, :last-child)
    • Pseudo-elements (e.g., ::before, ::after)
    • Properties like position, 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.

Conclusion

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).

References:

https://www.keycloak.org/docs/latest/server_admin/index.html

Related Posts