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 Clickatell (https://www.clickatell.com)
1. Create Clickatell account
If you wish to use Clickatell you'll first need to sign up for a Developer Central account in order to have access to the tools required for providing access to an SMS Gateway. To do this, visit the main web site at http://www.clickatell.com/ and click Register at the top.
Enter your new account details, accept the terms and conditions and click the Register button.
You should receive an email from Clickatell to confirm your address. After clicking the link in that email you should get to the logon screen. Enter your credentials and log on.
2. Configure Clickatell
There are 3 steps to configuring your Clickatell account. First, complete step 1 and add a test mobile phone number (and activate it when an SMS is sent to your phone).
Clickatell creates a default SMS integration for you, so we can edit this. Click on the API key to open the integration.
In the details tab, alter the name and details field to something more memorable (in this case LogonBox and SMS for Password Reset from LogonBox).
Make a note of the API key and click on the Settings tab.
It can be useful to have Clickatell convert your phone numbers to the correct format it needs, so turn on the option for Convert mobile numbers into international format and choose your country.
Click Save to update the integration then click Activate.
Now complete Step 3, Billing
3. Authentication Scheme
At this stage, it is important to note that you can apply different authentication flows for four different types of logon: User Login, Account Unlock, Admin, SSO and Password Reset.
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 purple User Selective 2FA one. Let’s replace Security Questions 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.
Scroll down and click Save.
4. Authentication Options
Now navigate to Authentication Flows->Authentication Options->SMS Code. As you will be sending messages to mobile devices and the request is performed via a HTTP call, set Symbol Chars to 0 on the Password tab. This will cause errors in the HTTP call otherwise, but it is a generally good idea to disable symbols due to the extra difficulty of typing these characters on a mobile keyboard.
Now click on the SMS tab.
Change the Provider from LogonBox Cloud SMS to Generic HTTP API.
Set the Default Country Code to the country where most of your users reside.
Change the Message so that any spaces are replaced with %20. i.e Your%20authentication%20code%20is%20${code}
You can also set some other options here such as attempting to read mobile numbers from your directory and write them back to AD if they don't exist there.
Click Apply.
6. Set up API call
Now navigate to Messages->Settings->SMS(HTTP).
We need to set the contents of the HTTP request that is sent out in the format required by Clickatell.
Clickatell need to know the following items of information:
- Your API Key
- The mobile number to send messages to (we will use a LogonBox replacement attribute for this).
- The message to send.
As this is a GET request, we can do this in a single URL call, so set URL to the below, replacing the apiKey value with the one you noted down earlier.
https://platform.clickatell.com/messages/http/send?apiKey=hwYPg7BfSqW4yPfkAyMofQ==&to=${e164Number}&content=${message}
Click Apply to save the changes.
7. Testing
Let’s perform an example Reset Password action to ensure this is now working. On the portal 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 One Time Password, you are then allowed and prompted to change your password.
Your password reset has been successful.
