Escaping HTML values in emails

In Airlock IAM, several plugins generate email messages and send them to end-users. These emails can contain variables, such as salutation, first name and surname of an end-user. The values of the variables are provided by so-called value providers, such as the Context Data Map value provider for end-user data.

In IAM, emails are sent in plain text by default. Emails in HTML mode present a risk if the variables in HTML are not encoded. However, some situations may require sending emails as HTML. In this case, make sure to escape the HTML values. This article explains how to configure this.

There are several options to escape HTML values in an email:

• Option 1 - Escape all HTML values
• The property Escape Values in HTML allows escaping all HTML values in an email. This property is enabled by default in IAM. It is available in all plugins that replace variables with values in emails.
• The following plugins contain the Escape Values in HTML property:
• Email Message Provider
• Email Identity Verification Step
• Email Notification Step
• Flow-based Password Reset
• Send Email Link Step


More recent plugins, such as the Email Event Subscriber, no longer allow unescaped HTML values in emails. They always automatically escape HTML values when Send As HTML is activated.

• Option 2 - Selectively escape specific HTML values
• IAM also supports the escaping of specific HTML variables selectively, with the Transforming Value Map Provider feature. This feature allows configuring a list of value providers together with an HTML String Escaper plugin. All values provided by the value providers in the list will be HTML-escaped; all values provided by other value providers appear unescaped in HTML code in the mail. Thus, the feature guarantees backwards compatibility for customers who use legitimate HTML in their user data that should not be escaped, such as names, e.g., Phileas O'Connor.


For security reasons, only use unescaped HTML values in emails for low-security applications and if it is considered safe!

The section below explains how to configure the Transforming Value Map Provider feature.

To escape specific HTML values in an email using the Transforming Value Map Provider feature, proceed as follows:

1. In the Loginapp, go to the dialog of the relevant email-generating plugin. In this dialog, go to the property where you specifiy the value providers for variables in emails. For example, in the Email Message Provider plugin, this is the property Value Providers.
2. In this property, first create and edit the value provider maps that provide values for variables that must not be HTML-escaped.
3. Then, at the end of the list, create the Transforming Value Map Provider plugin for the HTML-escaped variables. Edit the plugin as follows:
4. In property Value Providers, specify the maps providing the values that must be HTML-escaped. If required, you can add more than one provider map.
5. In property Transformations, create the HTML String Escaper plugin.
6. Return to the mail-generating plugin. Disable the property Escape Values in HTML, if available (it may be in the section Advanced Settings).
7. Activate your configuration.
8. The emails sent by IAM in HTML mode will now HTML-escape the values specified above.