Integrate SMS-OTPs to your applications with the WSO2 Identity Server
WSO2 Identity Server (WSO2IS) now supports integrating SMS-OTPs for customizations in addition to multi-factor authorization (MFA).
As an example, let’s say you are integrating the WSO2 Identity provider in your environment. When a user who is already logged into your application wants to do a transaction you want to trigger an added security functionality, and for this, you want to send SMS-OTP for that particular user’s mobile phone thereby verifying the transaction is done by the same person who uses the application. Previously it cannot be done with WSO2IS but now you can do it with newly introduced SMS-OTP REST API endpoints.
What is OTP?
OTP stands for One-Time Password, which is a password that is valid for only one login session or transaction, on a computer system or other digital device.
How to use SMS-OTPs with the WSO2IS
There are two ways to integrate SMS-OTPs into your application,
- Using SMS-OTP as a service
- Using SMS-OTP REST APIs
Using SMS-OTP as a service
1. Build org.wso2.carbon.extension.identity.smsotp.common from here, using mvn clean install command and put it in the <IS_HOME>/repository/components/dropins location.
2. Add the below configurations to the <IS_HOME>/repository/conf/deployment.toml file.
3. If notifications are managed by the Identity Server, configure the SMS template by appending below at the end of the <IS_HOME>/repository/conf/sms/sms-templates-admin-config.xml file.
4. If notifications are managed by the Identity Server, configure the event publisher by creating SMSPublisher.xml file in the <IS_HOME>/deployment/server/eventpublishers/ directory.
5. Add org.wso2.carbon.extension.identity.smsotp.common as a dependency on your maven project.
6. To use SMS-OTP in your application you need to call, SMSOtpService.generateSMSOTP(userId); and need to pass the SCIM-ID (userId) of the user. (Below is a custom code snippet that can be used to get userID from username and tenantDomain by username)
If the properties.triggerNotification=true in the deployment.toml file configurations your application will receive a transactionId and smsOtp will be sent to the User’s mobile via WSO2IS. If the properties.triggerNotification=false your application will get smsOtp and transactioId both, because we expect that your application will send that smsOtp via an external SMS provider.
7. To validate SMS-OTP you need to pass the below parameters.
smsOtp — SMS-OTP valuetransactionId — transactionId generated when the SMS-OTP is generated.userId — User’s ID, (SCIM-ID of the user)
Then you need to call SMSOtpService.validateSMSOTP(transactionId, userID, smsOTP); to validate your SMS-OTP. (Below is a custom code snippet that can be used to get userID from username and tenantDomain by username)
Using REST APIs
To run the REST APIs for SMS-OTP, you need to configure the SMS-OTP service as mentioned in the above 1–4 steps. Then follow the below steps.
- First, build
org.wso2.carbon.identity.api.otp.service.smsotpfrom here, usingmvn clean installcommand and put it in the <IS_HOME>/repository/deployment/server/webapps location. - Next, add Permissions
- Start WSO2 identity server and log in to management console https://<hostname>:<port>/carbon/admin/login.jsp
- Go to
Main -> Registry -> Browse -> /_system/governance/permission/admin/manage/identity/authentication/Add Collection, and gave that collection nameotp. Inside the newly created collection, there is an area to add properties, click there to add property and give name asnameand value asotp. - Like that create two more permission collections inside the newly created
otppermission as below.
/_system/governance/permission/admin/manage/identity/authentication/otp/generate this permission is to generate the otp.
/_system/governance/permission/admin/manage/identity/authentication/otp/validate this permission is to validate the otp.
- Go to
Main -> Identity -> Users and roles -> add -> add new roleand create a role withgeneratepermission and another role withvalidatepermission. - Assign role with
generateto some less privileged user and assign a role withvalidatepermission to users you need OTP created.
3. Go to the <IS_HOME>/repository/conf/deployment.toml file, and add the below configurations.
4. To generate SMS-OTP you can use below CURLs
carbon.supertenanthttps://{server-url}:{server-port}/api/identity/sms-otp/v1/smsotp/generate
curl -X 'POST' \
'https://localhost:9443/api/identity/sms-otp/v1/smsotp/generate' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"userId": "8b1cc9c4-b671-448a-a334-5afe838a4a3b"
}'
Other tenants
https://{server-url}:{server-port}/t/{tenant-name}/api/identity/sms-otp/v1/smsotp/generate
curl -X 'POST' \
'https://localhost:9443/t/cloud.com/api/identity/sms-otp/v1/smsotp/generate' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"userId": "8b1xx9c4-b671-448a-a334-5afe838a4a3b"
}'5. To validate SMS-OTP you can use below CURLs
carbon.supertenanthttps://{server-url}:{server-port}/api/identity/sms-otp/v1/smsotp/validate
curl -X 'POST' \
'https://localhost:9443/api/identity/sms-otp/v1/smsotp/validate' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"userId": "8b1cc9c4-b671-448a-a334-5afe838a4a3b",
"transactionId": "string",
"smsOTP": "string"
}'
Other tenants
https://{server-url}:{server-port}/t/{tenant-name}/api/identity/sms-otp/v1/smsotp/validate
curl -X 'POST' \
'https://localhost:9443/t/cloud.com/api/identity/sms-otp/v1/smsotp/validate' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"userId": "8b1cc9c4-b671-448a-a334-5afe838a4a3b",
"transactionId": "string",
"smsOTP": "string"
}'You can find the JSON collection for the REST APIs for SMS-OTPs here and the API contract here.
This only works with WSO2IS-5.10 and for other versions this is outdated.
