Keycloak: configure new EmailTemplateProvider

Overview

Keycloak is an open-source identity and access management solution which makes it easy to secure modern applications and services.

Keycloak comes with its own Email template provider FreeMarkerEmailTemplateProvider that contains all method senders needed .

In some use cases we need to use a custom Email template provider, to override or change some attribute for the email template, and in this topic i will explain how to do it .

Running the Keycloak server

There are many ways to run the keycloak server , in this topic we will use the:

• Traditional way :
  - Download keycloak from : https://www.keycloak.org/downloads.html
  - Run keycloak script: bin/standalone.sh
• Docker way :
  you can use the docker compose file under the github project

GitHub - sKaouech/kseasy-keycloak

Create the new Email Template Provider

Create a spring-boot project

• Add those dependencies in the pom file :

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-core</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-server-spi</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-server-spi-private</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-services</artifactId>
    <scope>provided</scope>
</dependency>

• We need to implemante EmailTemplateProvider interface and implement all needed methods

public class CustomFreeMarkerEmailTemplateProvider implements EmailTemplateProvider {

• Apport same change to the default method sender

@Override
public void sendVerifyEmail(String link, long expirationInMinutes) throws EmailException {
    Map<String, Object> attributes = new HashMap<>(this.attributes);
    attributes.put("user", new ProfileBean(user));
    addLinkInfoIntoAttributes(link, expirationInMinutes, attributes);

    attributes.put("realmName", getRealmName());

    send("emailVerificationSubject", "custom-email-verification.ftl", attributes);
}

• Implement EmailTemplateProviderFactory

public class CustomFreeMarkerEmailTemplateProviderFactory implements EmailTemplateProviderFactory {

    private FreeMarkerUtil freeMarker;

Create a file in resources/META-INF/services/org.keycloak.email.EmailTemplateProviderFactory
add under the file this line :

com.dealtobook.freemarker.CustomFreeMarkerEmailTemplateProviderFactory

Create a file under resources/META-INF/jboss-deployment-structure.xml
add under the file those lines :

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.keycloak.keycloak-core"/>
            <module name="org.keycloak.keycloak-services"/>
            <module name="org.freemarker"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

• Build the project to generate the jar file

mvn clean install

• Copy the jar in the target folder to the /opt/jboss/keycloak/standalone/deployments/ folder. Or when using Docker mount the file ./kseasy-freemarker.jar:/opt/jboss/keycloak/standalone/deployments/kseasy-freemarker.jar

Enable the new email template provider

• We need to ignore the default email template freemarker :
  Add this code to the standalone.xml file (mount the file if you use docker to run keycloak)

<spi name="emailTemplate">
    <provider name="freemarker" enabled="false"/>
</spi>

Open Keycloak and verify on the server info that the default email template provider is replaced with the new one , you can access to this page with this link : http://localhost:8080/auth/admin/master/console/#/server-info/providers

View the complete source code on github.com/sKaouech