Since moving to WSO2IS v5.3.0 onwards a lot of things changed. Using the Axis2 layer to configure email support became a legacy solution. Meaning that there is no guarantee that the email plugin we’ve published in 2016 will work now. Using the CEP engine integrated with Identity Server is the primary approach chosen by WSO2.
This blogpost will present a new solution for configuring multi-tenant specific SMTP settings for email events triggered by the Identity Server.
Introduction
For WSO2 Identity Server v5.3.0 onwards there are 2 ways how to configure email SMTP. You can edit the {WSO2 home}/repository/conf/axis2/axis2.xml file and activate the email transport sender. This is the old legacy way, and is not advised to use anymore. The new approach is to configure the {WSO2 home}/repository/conf/output-event-adapters.xml file. In there we have a email type adapter configuration. In the Identity Server documentation you can find exactly how to configure this part. But we are not going to do that here. I will tell you why.
Problems
The email type adapter doesn’t support tenant specific settings. There is no way how to introduce SMTP settings per tenant. The output-event-adapters.xml only accepts one configuraton per type. There is no way to placehold several XML blocks per email type so that you can use each copy for a tenant. In the tenant specific EmailPublisher.xml there is no way to add SMTP settings from the tenant. We are talking about the content in /repository/tenants/[some number]/eventpublishers/EmailPublisher.xml
So, I was forced to implement something that makes WSO2 IS able to do SMTP settings per tenant.
Approach
The adapters configured inside the `output-event-adapters.xml` are specific java OSGi module implementations. And the XML file itself is part of a WSO2 technology called the CEP, Complex Event Processor. So the java component that I eventually implemented is an Output Event Adapter as “tenantemail” type. What I eventually reached with this solution:
SMTP settings for a tenant are set as dynamical parameters inside an event publisher. In our case in the EmailPublisher.xml that is generated for the tenant. Inside the output-event-adapters.xml we are only left with server specific properties. Email sessions from `javax.mail` are now thread save and created each time when an email is send. This solves all the concurrency issues.
How to deploy and configure
Take the jar `output.adapter.tenantemail-1.0.0.jar` and place it in the directory `{WSO2 home}/repository/components/dropins`. When starting up the server this jar will be initialised as an OSGi module.
In the `{WSO2 home}/repository/conf/output-event-adapters.xml` add the following XML block:
This will initialise the adapter, and from then on listen on any output events that can occur.
When you created one or more tenants in WSO2IS (see previous blogpost for guidelines) the server generated sub-directories inside `{WSO2 home}/repository/tenants`. Notice that they all have numbers like `[1], [2], …`. These numbers represent tenant ID’s that are assigned by WSO2IS to specific tenant domains. When you login as tenant admin to the carbon admin console, in the application log `{WSO2 home}/repository/logs/wso2carbon.log` you will see a line with the tenant admin username and the tenant ID that is attached to the tenant domain name. This is a way to identify the numbers.
So, when editing the `{WSO2 home}/repository/tenants/[tenant ID]/eventpublishers/EmailPublisher.xml`, add the following configuration:
When you comment out the user and password, and set `mail.smtp.auth=true`, the module will construct a session that authenticates to the SMTP server. This can be done with or without TLS support, depending onthe SMTP server specifications.
When you set `mail.session.debug=true` you can follow the SMTP server response in the application log. This is very handy to check where in the transport protocol something goes wrong.
With the normal email type adapter we didn’t had the ability to configure more SMTP server locations. Another new thing is that the EmailPublisher file is hot deployable. When changing and saving the file, WSO2IS will detect there is a change, and it will redeploy the settings, without having to restart the server. (in the old situation we needed a server restart)
Adapter logs
If you want to trace the process of the adapter you can always add the following inside `/repository/conf/log4j.properties`:
log4j.logger.com.yenlo.wso2.carbon.event.output.adapter.tenantemail=DEBUG, CARBON_CONSOLE,CARBON_LOGFILE
Run it, and the results
Start the WSO2 server. As a usecase you can try out self-registration. When testing it locally you need: - A fakeSMTP server running for instance on localhost port 25. - Configuring the server that it supports self-registration.
– For testing do self-registration at https://localhost:9443/dashboard - Observe the application logs, and observe incoming emails in the SMTP server.
Golden tip: For a more realistic test scenario you can also use SendGrid SMTP. For this you need to create an account on sendgrid.net and create an API key which you will use to connect to the SMTP server. Here’s an example configuration in the `EmailPublisher.xml`.
{username}@{tenant domain}
After the process finished 2 things can be noticed:
- The email has tenant specific headers, with tenant specific activation URL’s.
- The user is created under the tenant domain. The tenant admin can lookup the user in the carbon admin console.
If you want to use this adapter
Please keep in mind that my self made adapter is tested with WSO2IS version 5.4.0 vanilla. Trying to use it on different versions might result in side effects that it doesn’t function as it should. This is because there are a list of dependencies from libraries that are packaged with WSO2IS v5.4.0. Trying to make it work on for instance version 5.3.0, 5.4.1, 5.6.0 or any other versions should be combined with a rebuild of the java component with the correct dependency versions included.
Conclusion
WSO2 IS (v5.4.0) does have all the capabilities for multi-tenancy support. But on the configuration side, for instance in the case of doing SMTP settings for a tenant, we needed a custom extention to give us all the possibilities. Meaning, that you have to get your hands dirty on some java implementations. But if all that is done and throughly tested, WSO2 gives the possibility to adapt and cover the multi-tenant SMTP use case.
