Configuring WSO2 Identity Server to Support Multiple notification channels
In my previous blogs I’ve explained how user self registration works explained about the API requests and responses. From this blog, I take you the process of configuring the Identity Server. Please note that this feature is available for WSO2 IS 5.7.0 WUM updated version and will be available for WSO2 IS 5.10.0 which will be released in the near future.
Configurations to the server
- Configure output-event-adapters.xml to send emails (Refer to email configuration documentation).
- The email templates are stored in email-admin-config.xml in <HOME>/repository/conf/email folder. Add the SMS templates to the .xml with ‘sms’ prefix to the beginning. ( NOTE: prefix is case sensitive. Always use lower case characters)
Eg: The template name of email account confirmation is
type=”accountConfirmation” display=”AccountConfirmation”Therefore, the name of the SMS template should be as follows.
type=”smsAccountconfirmation” display=”smsAccountconfirmation”Sample SMS Template
(Note: The body of the template is customizable. Make sure to include {{confirmation-code}} parameter as shown below)
<configuration type="smsaccountconfirmation" display="smsaccountconfirmation" locale="en_US" emailContentType="text/html">
<subject>WSO2 - Self Registration OTP</subject>
<body>Your OTP is : {{confirmation-code}}</body>
<footer></footer>
</configuration>3. Create a new stream and add it to <HOME>/repository/deployment/server /eventstreams. Refer to Managing Notification Internally section for more details.
4. Create a new Publisher and add it to <HOME>/repository/deployment /server/ eventpublishers. Refer to Managing Notification Internally section for more details.
5.Configure identity-event.properties in <HOME>/repository/conf/identity folder to subscribe event handler for triggering notifications. Refer to the Notification handler configurations in identity-event.properties section for more details.
6. The new feature introduces new configurations to resolve the notification channel. Add the following configurations to the identity.xml in <HOME> /repository/conf/identity folder within the Server tags. (NOTE: This configuration will only affect user self-registration scenario)
<Notification> <DefaultNotificationChannel>EMAIL</DefaultNotificationChannel> <ResolveNotificationChannels>
<Enable>true</Enable>
</ResolveNotificationChannels>
</Notification>DefaultNotificationChannel tag will determine the default notification channel for the server. The default value of the property is EMAIL.
NOTE: Currently, Identity Server only supports EMAIL and SMS as communication channels. Providing any other value will result in errors (NOTE: This configuration is case sensitive. Always use uppercase characters)
ResolveNotificationChannels tag will enable resolving the notification channels criteria which I explained in my previous blog to resolve the notification channel. If the property is not enabled, the notification channel will be always resolved to the default notification channel. The default value of the property is false.
7. Add following configurations to identity.xml in <HOME>/repository/conf /identity folder inside<SelfRegistration> tags.
<RegisterWithVerifiedChannels>true</RegisterWithVerifiedChannels>
<API>
<EnableDetailedResponseBody>true</EnableDetailedResponseBody>
</API>RegisterWithVerifiedChannels will enable Self-register after pre-confirmation of the user account, with verified claims. If the property is not enabled, account confirmation is needed even though the account is pre-confirmed. The default value of the property is false.
EnableDetailedResponseBody will enable detailed API responses. The default value of the property is false.
8. Restart the server to apply configurations.
User Self Registration Configurations
- Navigate to Main > Claims > List and enable Email Verified and Phone Verified claims for the default profile. (NOTE: These claims will keep track of the verified status of the communication channels)
- Navigate to Main > Claim > Add and add the following identity claim to track the user preferred notification channel.
- Claim: http://wso2.org/claims/identity/preferredChannel (NOTE: DO NOT change the given claim. A different claim will not support the feature)
- After adding the claim, navigate to Main > Claim > List and enable the above claim for the default profile.
If you have enabled the claims, the profile of the user will look like follows.
3. Navigate to Resident IDP Configurations > Account Management Policies > User Self Registration and enable User self registration. NOTE: A new configuration has been provided to configure the validation time of the OTP codes. Make sure to set the validity time of an SMS OTP.
4. Enable Internal Notification Management to send account confirmation notification from Identity Server. With the new feature Identity Server is capable of verifying via both EMAIL and SMS channels.
Managing Notification Internally
If you wish to use internal notification management feature where the server sends the emails and SMS, then you have to configure a separate stream and a publisher to send SMS.
Following is a sample stream that I’ve written. You need to add the stream to <product_home>/repository/deployment/server/eventstreams folder.
{"name": "id_gov_sms_notify_stream","version": "1.0.0" }To send SMS, you can configure a SMS service or call a SMS sending REST API. For the following sample publisher, I have used a SMS sending REST API with the http output adapter. (Refer to http publisher documentation for more details)
<?xml version="1.0" encoding="UTF-8"?><eventPublisher name="HTTPOutputEventAdapter" processing="enable" statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
<from streamName="id_gov_sms_notify_stream" version="1.0.0"/><mapping customMapping="enable" type="json">
<inline>
{"api_key"="<api_key>",
"api_secret"="<api secret>",
"from"="NEXMO",
"to"={{mobile}},
"text"={{body}}}
</inline></mapping>
<to eventAdapterType="http">
<property name="http.client.method">httpPost</property>
<property name="http.url">https://rest.nexmo.com/sms/json</property></to>
</eventPublisher>
NOTE: The values within <...> needs to be hard coded and the values within {{...}} needs to be in the stream as key value pairs.
Notification handler configurations in identity-event.properties
You have to configure this file only if you wish to manage notifications internally. When an SMS needs to be sent an event with name TRIGGER_SMS_NOTIFICATION will be triggered. In order to send a SMS you need to subscribe a notification handler and a stream for TRIGGER_SMS_NOTIFICATION event.
Sample Configuration
module.name.13=default.notification.sender default.notification.sender.subscription.1=TRIGGER_SMS_NOTIFICATION 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 I will explain more about the default notification handler and configurations from my next blog about the notification handler.
Alright. There you have it. Now you have configured WSO2 Identity Server to send both emails and SMS at the user self registration. Thank you for reading the blog and hope it helped.