SMS OTP Configurations

This page lists out all the advanced configurations related to SMS OTP.

The following code snippet shows a sample SMSOTP configuration in the <IS_HOME>/repository/conf/deployment.toml file.


SMSOTPAuthenticationEndpointURL= "/smsotpauthenticationendpoint/smsotp.jsp"
SMSOTPAuthenticationEndpointErrorPage= "/smsotpauthenticationendpoint/smsotpError.jsp"
MobileNumberRegPage = "/smsotpauthenticationendpoint/mobile.jsp"
RetryEnable = true
ResendEnable = true
BackupCode = true
SMSOTPEnableByUserClaim = true
SMSOTPMandatory = false
CaptureAndUpdateMobileNumber = true
SendOTPDirectlyToMobile = false
redirectToMultiOptionPageOnFailure = false

The parameter values given above show the default configurations in WSO2 Identity Server.

If you wish to change a parameter value to something other than the default value, add the configuration to the deployment.toml file using the following format.

<Property-name> = "<Property-value>"


Enable or disable the authenticator.


Authentication endpoint URL of the authenticator.


Error page that will be displayed in case of an authentication failure.


Range of usable mobile numbers to send SMSs.


Define whether to retry or not.


Define whether to enable resending the SMSOTP or not in case a user enters an incorrect code.


Define whether to use a backup code instead of the actual SMS code or not.


If the value is true, the second step will be enabled by the admin. The user cannot be authenticated without SMS OTP authentication. This parameter is used for both super tenant and tenant in the configuration. The value can be true or false.


Disable the 'SMS OTP disabling by user' functionality. The value can be either true or false. If the value is set to true, the user can enable and disable the SMS OTP according to what the admin selects as the SMSOTPMandatory parameter value.


When SMSOTPMandatory is set to true and the user forgets to update the mobile number in a specific user profile where this property is set to true, the user can update a mobile claim with value during the authentication time and use that mobile number to send OTP. This update functionality will happen in the first login only. For the next logins, the updated mobile number will be used.


When SMSOTPMandatory is set to true and the user does not exist in the user store and if the admin sets SendOTPDirectlyToMobile to true , the user can enter the mobile number in authentication time in a mobile number request page; the OTP will be directly sent to that mobile number.


During a failed attempt enable redirect to the Multi Option Page where the user can select the authentication mechanism.


SMS OTP does not have a default validity period hence you will have to explicitly configure it by adding the TokenExpiryTime parameter. The value provided for the parameter is considered as seconds.