Tenant Wise Email and SMS Notification Senders in WSO2 Identity Server
Different Notification Senders for Different Tenants
When you are using the WSO2 Identity Server you may have the requirement of sending notifications to the end-users based on the user-operations (examples: user onboarding, password recovery, username recovery).WSO2 IS has an eventing framework to trigger events based on user operations that are related to your business operations. Also, it has a notification service feature to send notifications to the end-users via the user’s preferred channel(email/SMS).
Why different notification senders for different tenants?
If you are using multi-tenancy support of WSO2 IS to maintain the identities of departments in the organization, in an isolated manner, configuring different notification senders may be a requirement.
For example, Your organization has two departments as engineering and finance . Identities of employees work in the engineering department and finance department are managed in engineering.com tenant and finance.com tenants separately. You may want to send user onboarding emails and all account recovery emails to the employees in the engineering department via SMTP Server1 and to the employees in the finance department via SMTP Server2 .
This guide helps you to get it done simply.
REST API for tenant-wise notification sender configurations
From IS-5.7.0 onwards tenant-wise notification sender configuration feature was supported[1][2]. But that configuration process is quite difficult for the system admin because the admin needs to upload a properly created event publisher XML file with the configuration. Therefore WSO2 IS-5.12.0-m5 has introduced a REST API to configure notification senders tenant-wise (See the feature development [3]) to make the tenant admin’s life easier. Identity Server generates the event publisher XML file based on the user input in REST API request payload. However, the configuration storing and loading mechanism (i.e backend logic) is the same as earlier.
Common details of the REST API
- This API can’t be used to configure notification senders for the super tenant (carbon.super). In other words, super tenant’s event publishers are not saved in the database. If you try to configure, the response will be
405 Method Not Allowed. - If you want to configure event publishers in carbon.super tenant, add or modify event publishers in
IS_HOME/repository/deployment/server/eventpublishers. For more information on writing an event publisher, see Event Publisher Types. - The following properties are used for internal operations. Therefore, avoid using these properties when configuring notification senders.
* streamName - The name of the event stream where events are picked for notification sending* version - The version of the event stream* type - Type of the notification sender (email/sms)
- name is not a required attribute to any notification sender configuration POST request payload. If the name is not defined the sender name is set to the corresponding default event publisher name in the super tenant.
Email - EmailPublisher
SMS - SMSPublisherIf a “name” is defined, there should be an already deployed event publisher in the super tenant with that name (check event publishers in IS_HOME/repository/deployment/server/eventpublishers).
- The URL encoded sender’s name should be used when invoking GET / DELETE requests on the following REST endpoints.
/api/server/v1/notification-senders/email/{email-sender-name}
/api/server/v1/notification-senders/sms/{sms-sender-name}- All endpoints are secured with config mgt related permission and scopes. Check the Permission required and Scope required mentioned for each endpoint and access the resource with relevant permissions and scopes. Otherwise, you will end up with
403 Forbiddenerror response.
REST API for Email sender configuration
- Currently, you can configure only email senders that work over SMTP.
- POST request payload has first-class support for the following attributes:
name
smtpServerHost
smtpPort
fromAddress
userName
password- If you want to configure any other property which should come into the email adaptor configuration define property keys with the exact names given in Email Event Publisher documentation.
example: If you want to configure maxThread = 200, and mail.smtp.starttls.enable = true, the properties attribute of the payload should be as follows.
"properties": [
{
"key": "maxThread",
"value": "200"
},
{
"key": "mail.smtp.starttls.enable",
"value": true
}
]REST API for SMS sender configuration
- The payload of SMS sending API varies based on the SMS provider (example: Vonage, Bulksms).
- Some SMS providers’ SMS sending API payloads are templated in the
IS_HOME/repository/conf/sms/sms-providers-api-body-templates.xmlfile. - Those templates have the minimum level of attributes (i.e. only the required attributes) of each SMS sending API.
- You can add new SMS providers’ payloads, or modify the existing SMS provider payloads by adding new attributes. After modifying that file, the identity server must be restarted.
example: You want to add the D7SMS provider’s SMS sending API template.
<configuration provider=”D7SMS”>
<body>
{"content": {{body}}, "from": $sender,"to": {{mobile}}}
</body>
</configuration>example: You want to add routingGroup attribute to the Bulksms template.
<configuration provider=”Bulksms”>
<body>
[{ “from”: $sender, “to”: {{mobile}}, “body”: {{body}}, “routingGroup”: $body.routingGroup}]
</body>
</configuration>- Attribute values that need to be replaced by POST /notification-senders/sms API’s input should be templated with a prefix, “$” in
IS_HOME/repository/conf/sms/sms-providers-api-body-templates.xmlfile.
example:
$sender will be replaced by the input value of the “sender” attribute.$body.routingGroup will be replaced by the input value of the property defined with key - “body.routingGroup”.
- The attribute values templated with
{{some-word}}(example: {{mobile}}, {{body}}) are the variables which will be replaced based on the event (eg: user onboarding, password recovery) data. - POST request payload has first-class support for the following attributes:
name
provider
providerURL
key
secret
sender- Properties in POST /notification-senders/sms request
- Properties that need to be included in SMS provider API’s body define with the prefix, ”body.”.
- If the property named “body” is present, the corresponding value will be used as the SMS provider API’s body. It means instead of defining the SMS sending API’s payload template in
IS_HOME/repository/conf/sms/sms-providers-api-body-templates.xml, you can provide the exact payload with values in thepropertiessection.
Example:
provider and providerURL are mandatory attributes. If you don’t have the D7SMS provider’s SMS sending API’s templated payload in the IS_HOME/repository/conf/sms/sms-providers-api-body-templates.xml file, you can add the body property as follows.
{
"provider": "D7SMS",
"providerURL": "",
"properties": [
{
"key": "body",
"value": "{"content": {{body}}, "from": "0771232345", "to": {{mobile}} }"
}
]
}3. If you want to add properties related to HTTPOutputEventAdaptor, define keys with the exact names defined in the HTTP Event Publisher documentation.
Example:
- Let’s assume you change the
Bulksmstemplate as follows.
<configuration provider=”Bulksms”>
<body>
[{ “from”: $sender, “to”: {{mobile}}, “body”: {{body}}, “routingGroup”: $body.routingGroup}]
</body>
</configuration>- The
POST /notification-senders/smsrequest should have a property with a key named “body.routingGroup”.
{
"provider": "Bulksms",
"providerURL": "https://webhook.site/9b79bebd-445a-4dec-ad5e-622b856fa184",
"key": "123",
"secret": "1234",
"sender": "073923902",
"properties": [
{
"key": "body.routingGroup",
"value": "ECONOMY"
}
]
}Postman collection to try out: https://app.getpostman.com/run-collection/7bc59cc3e9c958bffaf4
All Good! Now send your notification as you wish!!
References:
