Tenant Wise Email and SMS Notification Senders in WSO2 Identity Server

source: https://rightclickmedia.co.za/what-are-sms-and-email-campaigns/

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.

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 - SMSPublisher
  • 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 Forbidden error 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
"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.xml file.
  • 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.
<configuration provider=”D7SMS”> 
<body>
{"content": {{body}}, "from": $sender,"to": {{mobile}}}
</body>
</configuration>
<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.xml file.
$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
  1. Properties that need to be included in SMS provider API’s body define with the prefix, ”body.”.
  2. 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 the properties section.
{
"provider": "D7SMS",
"providerURL": "",
"properties": [
{
"key": "body",
"value": "{"content": {{body}}, "from": "0771232345", "to": {{mobile}} }"
}

]
}
  • Let’s assume you change the Bulksms template as follows.
<configuration provider=”Bulksms”> 
<body>
[{ “from”: $sender, “to”: {{mobile}}, “body”: {{body}},
“routingGroup”: $body.routingGroup}]
</body>
</configuration>
  • The POST /notification-senders/sms request 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"
}

]
}

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Anuradha Karunarathna

Anuradha Karunarathna

Senior Software Engineer@ WSO2 | Computer Science and Engineering graduate@ University of Moratuwa, SriLanka