4

I'm trying to display the company logo in the reset password email. I've already checked keycloak docs and found out it's not supported by them. I also tried encoding an image into base64 but Gmail doesn't support that. How can i do that?

javamat
  • 119
  • 1
  • 1
  • 7
  • Did you create custom email theme and override `password-reset.ftl`? – Vadim Ashikhman Aug 28 '19 at 13:11
  • Yes I did. I tried adding an image to theme/email/resources/img and reference to it by calling ${url.resourcePath}/img/myImage.jpg in img tag but still doesn't work – javamat Aug 29 '19 at 14:31

6 Answers6

4

You need to create a custom theme. Check Keycloak's docs chapter 3: docs

There are five types of themes/pages:

  • Account - Account management
  • Admin - Admin console
  • Email - Emails
  • Login - Login forms
  • Welcome - Welcome page

You can start with a checkout of this sample repository kc themes sample, edit templates and deploy it in your keycloak.

Like the link says... to deploy it:

Copy

Simplest way to deploy the themes is to copy src/main/resources/theme/* to themes/.

Module

Alternatively you can deploy as modules. This can be done by first running:

mvn clean install $KEYCLOAK_HOME/bin/jboss-cli.sh --command="module add --name=org.keycloak.example.themes --resources=target/keycloak-example-themes.jar"

Then open standalone/configuration/standalone.xml and register the theme module by adding:

<theme>
    ...
    <modules>
        <module>org.keycloak.example.themes</module>
    </modules>
</theme>

You can copy other themes or extend it copying from base templates to your custom themes project.

Email base templates: email templates

Take care to select same Keycloak version before checkout project and sources.

Steps to Add a logo to email template inside an existing custom theme

  1. Locate your template file: /html/password-reset.ftl (e.g. base sample file)

    <html>
    <body>
    ${kcSanitize(msg("passwordResetBodyHtml",link, linkExpiration, realmName, linkExpirationFormatter(linkExpiration)))?no_esc}
    </body>
    </html>
  1. Replace with your code. E.g. with a base64 image or a linked reference to your image file (https://static.myserver.com/image.png, etc ...)

    <html>
    <body>
        <div>
            <img src="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUA
    AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
        9TXL0Y4OHwAAAABJRU5ErkJggg==" alt="Red Logo">
        </div>
        <div>
        ${kcSanitize(msg("passwordResetBodyHtml",link, linkExpiration, realmName, linkExpirationFormatter(linkExpiration)))?no_esc}
        </div>
    </body>
    </html>

  1. Update your plain-text template too (if you need because not all client support html). You cannot add the image here but if a text message [file text/password-reset.ftl]

  2. Package and deploy your theme in Keycloak

  3. Select your email template in Realm Configuration tab

As you can see in class DefaultEmailSenderProvider.java Keycloak will try to send a HTML email and if you don't define it uses text-plain (file: text/password-reset.ftl

Update:

There are currently some limitations imposed by some email clients. I advise you to read the following note about it (read me).

As it says, many web clients do not display emails that contain more than one image in base64 embedded (or none of them).

Therefore a good strategy with Keycloak emails is to use a reference to an image that is served from a static content server (if you do not have one of them, keycloak is over a wildfly that could also be configured as a static server).

So, the best solution you can implement is to add your image as follows: Eg.

<img src = "https://static.myserver.com/static/logo.png" alt = "img" />
Ariel Carrera
  • 5,113
  • 25
  • 36
2

DefaultEmailSenderProvider class allows only for text and html content as multipart/alternative. This is not enough to have working well (in most mail clients) embedded image like logo or so.

The html part should be wrapped together with image(s) by the multipart/related section. Therefore, some custom EmailSenderProvider seems to be needed. It should expose another param for inline imagies which one could be embeded in html section. The result should be a structure similar to this below.

- alternative
-- text
-- related
--- html
--- inline image 
--- inline image

As I have spent some time on research which haven't brought any result yet I plan to make a request to keycloak contributors.

Here is a good explenation of how it works with link to interesting Apache project.

woocash
  • 36
  • 4
2

As @Ariel Carrera already mentioned, inline data uri src for images are not well-supported by clients such as gmail.

But instead of uploading your images somewhere externally to use it in the template, you can include an image that comes directly from your template, like so:

<img src="${url.resourcesUrl}/img/MyCompany_Logo.png" title="MyCompany" alt="MyCompany Logo">

For the above code to work, you need to have a file in the following directory of your theme:

mytheme/email/resources/img/MyCompany_Logo.png

Note: SVGs also have less support by email clients. I would recommend a PNG and not an SVG for your email template

Note:

I have implemented this on v18.x.x keycloak, not v18.x.x-legacy.

With the legacy versions I don't know if the same result is possible, because there are differences in the url.resourcesUrl path that is returned

josias
  • 1,326
  • 1
  • 12
  • 39
1

Here is my solution for the Keycloak 21.x, hope to help somebody to save more time.

1. First step is adding our logo to our theme:

themes/{THEME_NAME}/email/resources/images/logo.png

2. Then we need to access our hostname in the Keycloak. I am using Keycloak on the K8s environment so it is easy for me. I can use KC_HOSTNAME_URL and move forward. Afterward, we need to access this variable in our theme. So we need to define a variable in our theme.properties (create this file if it doesn't exist). I can split this step into two steps:
2.1. Create the theme.properties in the email directory (if doesn't exist)

/themes/{THEME_NAME}/email/theme.properties

2.2. Add a variable to set env. variable to it

hostnameUrl=${env.KC_HOSTNAME_URL}

3. Now, you can use this variable in the src of your logo image:

src="${properties.hostnameUrl!}${url.resourcesPath}/images/logo.png"

PS: Don't forget to set KC_HOSTNAME_URL (or any env. variable you defined for this purpose) while running your Keycloak.

GLinBoy
  • 606
  • 1
  • 10
  • 20
1

I was dealing with a similar problem on Keycloak version 19.0.3 when I was trying to access an image from the resources/img directory of my custom email theme.

Inside template.ftl:

...
<img src="${url.resourcesUrl}/img/logo.png">
...

caused a NPE because url was "null or missing" when trying to send a test email or when triggering an email after to a certain Keycloak event.

I'm unsure why this is the case because I was simply following the docs for version 19.0.3. which describe to use ${url.resourcesPath}.

The only thing that resolved my issue was to upgrade Keycloak to version 20.0.0. (I tested it with 21.1.1. as well).

Hope this helps someone out as well.

Patrick
  • 1,728
  • 2
  • 17
  • 30
0

A simple way to get the logo url correct in keycloak's reset password email is to use the link variable together with freemarker's built-in keep_before, effectively removing path section from reset password link and then adding url.resourcesPath variable plus the path to your logo saved in email theme:

<img src="${link?keep_before("/auth/realms/")}${url.resourcesPath}/images/logo.png" />
ahuemmer
  • 1,653
  • 9
  • 22
  • 29
Kulla
  • 1