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 Thetexting (https://thetexting.com)
1. Create a TheTexting account
If you wish to use TheTexting you'll first need to sign up for an account in order to have access to the tools required for providing access to their SMS. To do this, visit the main web site at https://thetexting.com and click Signup at the top.
Enter your new account details and click the Submit button.
You should receive an email to confirm your address as well as getting a text message to your mobile.
First enter the verification code and click Verify Contact, which should then give you a green tick.
Then click the link in that email you received, after which you proceed to the service:
2. Configure TheTexting
Click on Settings in the left menu.
You can purchase the number you will need here for when using the service.
This page also shows you the Key and Secret that you will need for the LogonBox service in the API Settings section.
Here we will use the default HTTP GET method, but you can reconfigure this if required.
3. Authentication Scheme
At this stage, it is important to note that you can apply different authentication flows for many different types of logon, including User Logon, Password Reset, Account Unlock, Admin Logon 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 edit on 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 at the bottom.
4. 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.
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 The Texting.
TheTexting needs to know the following items of information:
- Your API Key
- Your API Secret
- The number you're sending this from (this will be the number you purchase from TheTexting)
- The mobile number to send messages to (we will use a LogonBox replacement attribute for this).
- The message to send (which will also contain a replacement attribute for the password).
As this is a GET request, we can do this in a single URL call, so set URL to something like below, replacing the api_key and api_secret with the ones for your own configuration.
This example is using a test sandbox, so replace sandbox with the from number:
Click Apply to save the changes.
5. 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.
6. 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.
