Configuring Default Notification Handler in WSO2 Identity Server to send Emails and SMSes

WSO2 Identity Server (IS)can send different notifications to users based on different scenarios. For example, Self-Registration Confirmation notifications, Username, and Password Recovery notifications, Account Locked/Unlocked notifications. WSO2 IS is highly configurable to our own wish. So if I want to send a notification when a user account is deleted I can do it easily.

The smart people at WSO2 have made this identity server customizable and easily configurable. So to customize notification sending they have written a notification handler called DefaultNotificationHandler. Cool right???? Let me tell you how this works in a very abstract manner.

Let's consider the User-Self Registration scenario.

When a user self-register, the SelfRegistrationHandler triggers an event (In this scenario its TRIGGER_SMS_NOTIFICATION) and publish it to the event stream. From that stream of events, the DefaultNotificationHandler picks that event if the handler is already subscribed to that event. Then the handler process the data and pass it to the data stream so that the event adapters can send the processed data. Let's go back to the configurations. WSO2 IS 5.9.0 introduces a new configuration model. Therefore prior versions have a way of configuring the notification handler. In this blog, I will explain configuring in

• IS 5.8.0 and prior versions
• IS 5.10.0 and upper versions

Configuring in WSO2 IS 5.8.0 and prior versions

The following is a sample config to subscribe the handler to TRIGGER_SMS_NOTIFICATION event. Navigate to the identity-event.properties file found in the <IS_HOME>/repository/conf/identity folder and the sample config.

module.name.13=default.notification.sender
default.notification.sender.subscription.1=TRIGGER_SMS_NOTIFICATION
default.notification.sender.subscription.2=PRE_DELETE_USER
default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.stream=id_gov_sms_notify_stream:1.0.0
default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.claim.mobile=http://wso2.org/claims/mobile

identity-event.properties file has different handler configurations. In this case, number 13 is the next available config.

Different handlers of Identity Server has different names such as account.lock.handler, accountConfirmationValidation etc. So in this case the friendly name of DefaultNotificationHandler is default.notification.sender.

Now we need to subscribe the hander to different events. For that, we need to have a subscription number with the subscription keyword. In the above sample, the handler is subscribed to two events; TRIGGER_SMS_NOTIFICATION and PRE_DELETE_USER.

Then we need to specify a stream for the subscribed event. In order to do so, we need to use the event name with the stream keyword.

default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.stream=id_gov_sms_notify_stream:1.0.0

In the above sample, TRIGGER_SMS_NOTIFICATION event has been subscribed to id_gov_sms_notify_stream:1.0.0 . If we do not specify a stream, then the default stream id_gov_notify_stream:1.0.0 will be used.

Now the main configurations are finished. We can do several additions to the above events using several more configurations.

Notifications are sent to the user according to a notification template bind to that scenario. When an event is triggered, the event usually contains a template bound to that scenario (bound not to the event). But with the following configuration, the system admin to configure a specific template to a specific event.

default.notification.sender.subscription.PRE_DELETE_USER.notification_template=accountDeleteConfirmation

The above config binds accountDeleteConfirmation notification template to PRE_DELETE_USER event. That means, when a PRE_DELETE_USER event occurs, a notification will be sent to the user according to the template specified by accountDeleteConfirmation. In here notification_template is the keyword to specify a notification template to a specific event.

Another important feature of the defaultNotificationHandler is to prepare the values of the placeholders in the notification template and event publishers. Most of these placeholder values are inserted into the meta properties of the event by the previous handlers. If we want to read more values from the user profile, we and use the following config.

default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.claim.<sample_claim>=<sample_claim_uri>

The handler will get the value for the sample_claim_uri from the user’s profile and store it with the key as sample_claim . The claim is the keyword used to set the claims. Remember to add a placeHolder named sample_claim to either the template or publisher to observe the effect. According to my previous sample config, there the key(or placeholder) is mobile and the value claim is http://wso2.org/claims/mobile.

Let’s say you have a requirement to pass a property and value and pass it to the data stream, then you can use the following config.

default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.testcustomattribute=testattributevalue

This will make a key-value pair as testcustomattribute=testattributevalue and it will be passed in the data stream.

Configuring in WSO2 IS 5.10.0 and upper versions

Unlike in previous IS versions, the default notification handler is enabled in WSO2 IS 5.10.0 and by default, the handler is subscribed to TRIGGER_SMS_NOTIFICATION event with the stream set as id_gov_sms_notify_stream:1.0.0 . Therefore we need to specifically define the handler. Instead, we can change the existing configurations.

In IS 5.10.0 we can do all the configurations from the deployment.toml file. In order to subscribe default notification handler to more events, add the following config to the toml.

[identity_mgt.events.schemes.'default.notification.sender']subscriptions=["PRE_DELETE_USER","TRIGGER_SMS_NOTIFICATION"]

Note that even though I have wanted to subscribe the handler to PRE_DELETE_USER event, I have also specified the TRIGGER_SMS_NOTIFICATION event. That is to maintain the default configuration of the handler. This is equivalent to the following config in previous versions.

default.notification.sender.subscription.1=TRIGGER_SMS_NOTIFICATION
default.notification.sender.subscription.2=PRE_DELETE_USER

To configure a stream to a specific event, we can use the following config.

[identity_mgt.events.schemes.'default.notification.sender'.properties]
'subscription.PRE_DELETE_USER.stream' = "id_gov_notify_stream:1.0.0"

This configures PRE_DELETE_USER event to id_gov_notify_stream:1.0.0 stream. As in the previous versions, if we do not specify a stream, the event will be subscribed to the default stream id_gov_notify_stream:1.0.0.

In WSO2 IS, when an event is triggered, the event contains a template bound to that specific scenario (not to the event). But with the following config, we can bind a specific template to a specific event (not to a scenario).

[identity_mgt.events.schemes.'default.notification.sender'.properties]'subscription.PRE_DELETE_USER.notification_template' = "accountDeleteConfirmation"

A sample config would be as follows.

[identity_mgt.events.schemes.'default.notification.sender'.properties]'subscription.PRE_DELETE_USER.notification_template' = "accountDeleteConfirmation"

According to the above config, when a PRE_DELETE_USER event occurs, a notification will be sent to the user with the content in the AccountDeleteConfirmation template. Note that notification_template is the keyword to specify a notification template to a specific event.

As I specified earlier, the handler has the capability to read claims from the user profile which is bound to the particular event. Even though a triggered event has certain placeholders as key-value pairs, the following config is a nice way to add more placeholders to the template and to the data stream.

[identity_mgt.events.schemes.'default.notification.sender'.properties]
'subscription.<event_name>.claim.<sample_claim>'="<sample_claim_uri>"

A sample config would be as follows.

[identity_mgt.events.schemes.'default.notification.sender'.properties]
'subscription.PRE_DELETE_USER.claim.email'="http://wso2.org/claims/email"

According to the above config, I have created a key-value pair as email = http://wso2.org/claims/email. The claim is the keyword used to set the claims.

In order to pass a property and value and pass it to the data stream, then you can use the following config.

[identity_mgt.events.schemes.'default.notification.sender'.properties]
'subscription.TRIGGER_SMS_NOTIFICATION.testcustomattribute'="testattributevalue"

This will make a key-value pair as testcustomattribute=testattributevalue and it will be passed in the data stream.

Configuring in WSO2 IS 5.9.0

In IS 5.9.0, the default notification handler is not enabled by default. Therefore, we need to add it as a custom identity event handler. In order to do so, we need to obey the following j2 template in <is_home>/repository /resources/conf/templates/repository/conf/identity/identity-event.properties.j2 file.

# Custom event configuration.
{% set custom_count = count|length %}
{% for custom_event in event_handler %}
{% set index = custom_count + loop.index %}
module.name.{{index}}={{custom_event.name}}
{% for subscription in custom_event.subscriptions.toList()%}{{custom_event.name}}.subscription.{{loop.index}}={{subscription}}{% endfor %}{% for property_name,property_value in custom_event.properties.items()%}{{custom_event.name}}.{{property_name}}={{property_value}}{% endfor %}{% endfor %}

The toml config which satisfies the above template would be as follows.

[[event_handler]]
name="default.notification.sender"
subscriptions=["PRE_DELETE_USER","TRIGGER_SMS_NOTIFICATION"]
[event_handler.properties]
'subscription.PRE_DELETE_USER.claim.email'="http://wso2.org/claims/email"
'subscription.TRIGGER_SMS_NOTIFICATION.testcustomattribute'="testattributevalue"

If you have read the previous section about configuring in IS 5.10.0, you would understand the meaning of the lines of the above sample config. So I’m not gonna repeat the same stuff again.

So yeah, that's it. That’s how you configure the default notification handler to send notifications to any event that you want. I hope this was helpful.