[keycloak-dev] E-Mail handling in Keycloak

Thomas Darimont thomas.darimont at googlemail.com
Thu Jan 5 04:30:40 EST 2017

I did look for a JIRA Issue but couldn't find one.
There was one issue about being able to set custom smtp-headers:

@1) yes I'll send a PR ;-)

@2) The idea is to add a user specific bounce address to every email sent
out by keycloak.
So if an admin sends an email to a user with a non-existing email one would
get a bounce from the particular email-provider.
After some time the e-mail provider will sent a bounce mail to the address
that was mentioned in the
MAIL FROM, or to be more specific in the smtp.mailfrom SMTP-header header.

Those emails can now be collected in a central inbox. The e-mails contain
the previously set
bounce email address with some additional information like service, realm,
userId, e.g.:
bounces+sso_acme-test_0b21aecc-4145-464f-86fa-719559b08869 at example.org

This information can now be used to lookup the user with the bad email
address and flag the user
or even require the user to enter a new e-mail.

One could also use a similar trick to encode some additional information
like (user realm, user-d) into the
custom reply-to address.
Based on a generic Help Desk address like helpdesk at example.org one could
generate a user specific address like:
helpdesk+sso_realm-name_user-id at example.org

A CRM application could now lookup the user by it's user-id to add
additional information to the helpdesk ticket.

The following Java program demonstrates the usage of JavMail with SMTP
Envelope From.
See the attached image for how this will look for the end-user in gmail.

import java.util.Properties;

import javax.mail.Message.RecipientType;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;

import com.sun.mail.smtp.SMTPMessage;

public class JavaMailSmtpBounceExample {

    public static void main(String[] args) throws Exception {

        Properties properties = new Properties();
        properties.put("mail.smtp.auth", "false");
        properties.put("mail.smtp.host", "smtp4server");
        properties.put("mail.smtp.port", "25");

        Session session = Session.getInstance(properties);
        SMTPMessage smtpMessage = new SMTPMessage(session);
        smtpMessage.setContent("Hello World", "text/plain");
        smtpMessage.setSubject("Test Mail " + System.currentTimeMillis());

        String userDisplayName = "Thomas Darimont";
        String userId = "0b21aecc-4145-464f-86fa-719559b08869";
        String userEmail = "thomas.darimont at gmail.com";

        String realmDisplayName = "acme SSO (test)";
        String realmName = "acme-test";
        String replyToDisplayName = "Help Desk";
        String replyToEmailLocalPart = "helpdesk";
        String realmFromEmailLocalPart = "no-reply";
        String serviceDomain = "example.org";

        String to = String.format("\"%s\"<%s>", userDisplayName, userEmail);
        String from = String.format("\"%s\"<%s@%s>", realmDisplayName,
        String envelopeFrom = String.format("bounces+sso_%s_%s@%s",
realmName, userId,
        String replyTo = String.format("\"%s\"<%s@%s>", replyToDisplayName,
                replyToEmailLocalPart, serviceDomain);

        System.out.printf("to: %s%n", to);
        System.out.printf("from: %s%n", from);
        System.out.printf("envelopeFrom: %s%n", envelopeFrom);
        System.out.printf("replyTo: %s%n", replyTo);




to: "Thomas Darimont"<thomas.darimont at gmail.com>
from: "acme SSO (test)"<no-reply at example.org>
bounces+sso_acme-test_0b21aecc-4145-464f-86fa-719559b08869 at example.org
replyTo: "Help Desk"<helpdesk at example.org>

The email
bounces+sso_acme-test_0b21aecc-4145-464f-86fa-719559b08869 at example.org

2017-01-05 9:44 GMT+01:00 Stian Thorgersen <sthorger at redhat.com>:

> On 5 January 2017 at 09:21, Thomas Darimont <thomas.darimont at googlemail.co
> m> wrote:
>> Hello group,
>> currently Keycloak allows to configure the "from" address per realm which
>> all emails sent from that particular realm use.
>> Often a generic address like no-reply at mycorp.com or a realm specific
>> address like
>> no-reply-myrealm at mycorp.com is used as "from" address.
>> It would be nice if one would have more options here like:
>> 1) Use the realm name or a custom string as the display name for the
>> "from"
>> Address
>>    Display Name<actual-address at mycorp.com>
>>    e.g.: "MyCorp SSO"<no-reply at mycorp.com>
>>            "MyCorp Helpdesk"<helpdesk at mycorp.com>
> We had someone request that in the past and I think there's a issue
> already open for it. If not then you can create one. Would it come with a
> PR ;)?
>> 2) Allow to specify a Bounce Address (MAIL FROM) with some place-holders
>> (user-id, realm-id)
>>    e.g.: sso-bounces+${realm-id}_${user-id}@mycorp.com
>>   This is especially useful when integrating with legacy user stores with
>> unreliable e-mail addresses.
> Can you explain this a bit more as I don't understand this
>> Shall I create JIRA issues for that?
>> Cheers,
>> Thomas
>> _______________________________________________
>> keycloak-dev mailing list
>> keycloak-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/keycloak-dev

More information about the keycloak-dev mailing list