Monday, August 8, 2016

Email Templates in Identity Management Feature of WSO2 Products

The Identity Management feature of WSO2 products comes with several different email templates that are used to send emails to end users in different user information recovery and identity management flows.

Some examples would be Temporary Password, Password Reset, One Time Password [1], Ask Password [2], Account Confirmation, Account Unlock and Account Id Recovery [3].

You can go to Configure -> Email Templates and view these email templates, if the Identity Management feature is installed in the particular WSO2 product. In a product like WSO2 Identity Server, this feature is by default installed. In this demonstration, I am using WSO2 Identity Server 5.1.0 which is the latest released version of IS at the time of this writing.



These default email templates are defined in SERVER_HOME/repository/conf/email/email-admin-config.xml file.

If you have not opened any email template from the Management Console and saved it, you can directly do the modifications you need to do in this email-admin-config.xml file.

However if you have opened an email template from Management Console and clicked on the Save button at-least once, thereafter the changes you do in email-admin-config.xml file will not appear in the email templates shown in management console (for already created tenants).


The reason is, when you click the Save button for any email template from Management Console, it takes a copy of the email-admin-config.xml file and creates  a registry resource in /_system/config/identity/config/ path with the name emailTemplate.

This registry resource contains the contents of the email-admin-config.xml file at the time of creation of this resource.

If you have already saved an email template and if this registry resource is already created, then the changes you make in email-admin-config.xml file will not be visible in the email templates shown in Management Console. However if you create a new tenant, at the time of tenant creation it will read the email-admin-config.xml file and create the email templates for that new tenant from the content of the xml file.

So the bottomline is, if you have the registry resource already created in your server and if you need to modify an email template, you have to do it through Management Console UI. (This behavior may be changed in future WSO2 products, but right now this works as discussed here)

The Commonly Supported Placeholders

All of these email templates support following placeholders which are dynamically resolved according to the logged in user. When you have one of these placeholders in the email template, it will be replaced by the logged in user’s particular attribute in the email received by the end user.

{first-name}
{user-name}
{userstore-domain}
{tenant-domain}

Apart from that, several other different placeholders are supported in different email templates as given below.

Email Template
Supported Placeholder/s
Temporary Password
{temporary-password}
Password Reset
{confirmation-code}
One Time Password
{otp-password}
Ask Password
{confirmation-code}
Account Confirmation
{confirmation-code}


These placeholders will be replaced by the actual value for that when the email is sent to the user.

At the moment WSO2 servers do not support sending HTML based emails but it only supports text based emails. However it is possible to write your own email templates and write your own email sending module to send notifications to users. This I will discuss in a separate post.

References


Tharindu Edirisinghe
Platform Security Team
WSO2

No comments:

Post a Comment