Introduction
LogonBox supports various methods of One-Time Password Delivery, which can be used for Password Resets, Unlocking Accounts, or even just logging on to the user or admin portals.
The method of delivery of One-Time Passwords is usually via Email, but in this article we will show you how to utilise an SMS service that uses a HTTP API to send messages.
For this example, we will be using a service run by CM.com (https://www.cm.com/)
Create CM.com account
If you wish to use cm.com you'll first need to sign up for the service. To do this, visit the main web site and click the Sign Up button.
Create your account and log in to the cm.com web site.
Configure cm.com
There is not really any configuration needed other than to ensure you have the Communications Platform plan and the Messaging Gateway API enabled, but you do need to get your API details so we can send via the HTTP API.
To do this, click on the Messaging Gateway menu, then click Copy Token next to the Product token.
From this same page, also copy the URL next to Service URL.
Authentication Scheme
At this stage, it is important to note that you can apply different authentication flows for different types of logon: User Login, Account Unlock, Admin, Password Reset, Windows Login etc.
Each of these have their own default authentication flow configured, but for this article we shall alter Password Reset as this is a common use case.
Navigate to Authentication Flows->Schemes and click the edit icon next to Password Reset. Note that by default this is configured with a blue Username module and a green User Selective 2FA one. Let’s replace User Selective 2FA with SMS. Click on the trashcan icon inside the User Selective 2FA module to remove it. Now click the plus icon next to SMS to add it into the authentication flow and click Save.
SMS Configuration
You can now navigate to Authentication Flows->Authentication Options->SMS. Set the Provider to CUSTOM.
Also on this page you can select some other options relating to SMS.
Use Directory Phones: If this option is ON, LogonBox will use mobile phone numbers synchronised from your user directory. If OFF, LogonBox will prompt users to enter their own mobile numbers.
Save Number to Directory: If this option is ON, if a user doesn't have a mobile stored in the user directory, LogonBox will save the first number added back to the user's account.
Default Country Code: This will add the default international dialling code to a user's number when sending to your SMS service. Start typing the country name and select it when it appears.
Prompt: The prompt to show the user on authentication.
Message: The SMS message text that is sent out. ${code} is a replacement variable that will contain the one time passcode. i.e: Your authentication code is ${code}.
Click Apply.
Now click on the SMS Code tab.
This is where you can alter some options relating to how an SMS code is generated. As you will be sending messages to mobile devices and the request is performed via a HTTP call, you may want to set Symbol Chars to 0 due to the extra difficulty of typing these characters on a mobile keyboard.
You can also define the length of the code in the Password Length section. Click Apply to save any changes.
As we need to do a POST request and hence are using the CUSTOM provider, we now need to create a Trigger to react to an SMS event.
Navigate to Business Rules->Triggers and click Create.
Give the Trigger a name (for example OTP to SMS) and for the Event start typing SMS Generated and select it when it appears.
Set Triggers On to Success and Triggers Task to HTTP Post XML/JSON.
Click the Request tab.
For the URL, paste in the Service URL as copied above.
Click the Content tab.
Set the Content Type to JSON.
For the Content, paste in the following JSON code, replacing <productToken> with the Product Token that was copied earlier.
{
"messages": {
"authentication": {
"productToken": "81ee3a0e-5de5-4c92-b64b-7a98346e1733"
},
"msg": [{
"body": {
"type": "auto",
"content": "Your OTP is ${attr.sms}"
},
"to": [{
"number": "${phone.e164}"
}],
"from": "TestSender",
"allowedChannels": ["SMS"]
}]
}
}
You may also choose to customize the message in the content, but ensure you include the replacement variable ${attr.sms}.
Click the Response tab.
Type in 200 and click the + button.
Click Create to create the Trigger.
Setting mobile numbers for users
Now we need to check that our users have phone numbers set on their accounts. If you are using Active Directory, as long as the user has their Mobile field completed in AD, your LogonBox will automatically use this.
To set up a user for SMS, all they need to do is log on as normal using the My Account link from the main portal.
If the user doesn't already have a mobile number stored on their account, they will be prompted to confirm the country code and their mobile number.
The user is now prompted to enter the code that is sent to their phone, which confirms deliverability.
If the user wants to change their mobile number at a later date, or add another number, they can go to their My Credentials->SMS Numbers menu.
Note: If a user has their number already in your User Directory, they will not get prompted to validate the number and it should just work for password resets.
Testing
Let’s perform an example Reset Password action to ensure this is now working. At the initial page, click Reset Password.
The next screen then prompts for the Username as expected. Type in the username and click Next.
Wait for your phone to receive the SMS message, then enter the password in the UI and complete the Logon.
After entering the SMS code, you are then allowed and prompted to change your password.
Your password reset has been successful.
