Self Registration with SMS Confirmation in WSO2 Identity Server 5.10.0 onwards

Register your users in an easy way

Setup WSO2 IS for self-registration

  1. Add an SMS event publisher with the file nameSMSPublisher.xml to <IS_HOME>/repository/deployment/server/eventpublishers location. You can use the provided sample. This is a sample publisher is for publishing the account confirmation code of signup flow to an SMS API. (NOTE: This file may be available in later versions like 5.12.0)

If your SMS provider is Vonage, the data inside the <inline> tag should be changed as follows (Instead of = , use : )



  • You need to provide the HTTP request body based on the selected SMS provider (NEXMO, Twillio, D7SMS, Bulksms, etc), between <inline></inline> tags.
  • In property http.url under <to></to> , you need to give the REST endpoint of the service the send SMS.
  • For the demo purpose, I have used a URL generated from Access here and get your unique URL to test the flow before going to a commercial SMS sender.

2. The accountconfirmation SMS template of <IS-HOME>/repository/conf/sms/sms-templates-admin-config.xml file is sent as the SMS. In case you want to change the message <body> should be changed and restart the server.

<configuration type="accountconfirmation" display="accountconfirmation" locale="en_US">
<body>Your One-Time Password is : {{confirmation-code}}</body>

3. When you are using the self-registration REST APIs if you wish to get detailed responses add the following config to the <IS-HOME>/repository/conf/deployment.toml file and restart the server. (Responses are enabled based on config in order to support backward compatibility)

enable_detailed_api_response = true

4. Add the following config to the <IS-HOME>/repository/conf/deployment.toml file based on your requirement.

  • default_notification_channel is used to set the default notification mechanism in IS. It can be configured as SMS/ EMAIL.
  • resolve_notification_channel is used to resolve the user preferred notification channel.
default_notification_channel = "SMS"
resolve_notification_channel = true

You can understand the notification channel resolution mechanism from this flow chart.

5. Sign in to the WSO2 Identity Server Management carbon Console https://<SERVER_HOST>:9443/carbon as an administrator(default username: password — admin: admin).

6. On the Main Menu of the Management Console, click Identity > Identity Providers > Resident. Under the Account Management Policies section, click User Self Registration.

Find what is meant by each config and alter accordingly. step 6

1. Self Registration API requests and responses [Define only one notification channel claim - selected mobile claim]

  • In my server resolve_notification_channel = true
  • Send a self-sign-up request defining mobile, but no email.
  • Response: 201 Created
{  "code": "USR-02001",  "message": "Successful user self registration. Pending account verification.",  "notificationChannel": "SMS"}
Signed up user profile on mgt console
  • Now you should have received an SMS notification.
  • If you have configured the webhook URL for testing purposes, you can find it like this.
response on
  • Now validate the code and make the user account unlocked.

Account Confirmation API requests and responses

Response: 202 Accepted

  • Go and check the user profile. Now the user is unlocked.

2. Self Registration API requests and responses [Define both email and mobile claims and also user-preferred notification channel]

  • Users can define the preferred notification channel using this claim.
{  "uri": "",  "value": "SMS"}
  • Code validation is the same as mentioned above step.

All done... 👊You can play around with the variables referring to the flow diagram and make your use case real!!

NOTE: UI support for notification channel selection on user self-registration is not available yet. It’s in the WSO2-IS roadmap.

Stay tuned for more WSO2 IS features!🎉🎉



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