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 ClickSend (https://www.clicksend.com/)
Create ClickSend account
If you wish to use ClickSend you'll first need to sign up for the service. To do this, visit the main web site and click the Get sending for free button.
Enter your new account details and click the Start Sending button.
You should receive an SMS from ClickSend to confirm your account which should then log you in to your dashboard.
Configure ClickSend
There is not really any configuration needed, but you do need to get your API details so we can send via the HTTP API.
To do this, click on the Developers menu on the left menu, then API Credentials.
Make a note of the username and API key as this will be needed for the LogonBox configuration.
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 Generic HTTP API.
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.
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. It is recommended to alter the message so that any spaces are replaced with %20. i.e: Your%20authentication%20code%20is%20${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.
Now navigate to Messages->Settings and select the SMS(HTTP) tab.
Now we need to set the contents of the HTTP request that is sent out in the format required by ClickSend.
ClickSend need to know the following items of information:
- Method
- Username
- 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 myUser and apiKey values with the one you noted down earlier.
https://api-mapper.clicksend.com/http/v2/send.php?method=http&username=myUser&key=apiKey&to=${e164Number}&message=${message}
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.
