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 Textmagic (https://www.textmagic.com/)
1. Configure Textmagic
Assuming you already have a Textmagic account, sign in to your account.
Navigate to Services->API and click Add new API key.
Give the new key a name (e.g LogonBox) and click Generate new key.
You will now see an API key that you can use in the below configuration.
Also note your virtual number that has been assigned to you.
2. Authentication Flow in LogonBox
At this stage, it is important to note that you can apply different authentication flows for several 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.
3. 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 Custom Event.
Set the Default Country Code to the country where most of your users reside.
Change the Message to meet your requirements, but ensure that you have ${code} in there, which will be the otp. i.e Your authentication code is ${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.
4. Set up API call
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 and for the Event, start typing SMS Generated and select it when it appears.
Set Triggers On to Success and Triggers Task to HTTP Form.
Click the Headers tab.
Click the + symbol, then in the left text box, type: X-TM-Username
In the right box, type your Textmagic username.
Click + again to create a new entry, enter X-TM-Key in the left box and your Textmagic API key in the right box.
Click the HTTP Form tab.
Set the Request Method to POST.
For the URL, enter: https://rest.textmagic.com/api/v2/messages
For Variables, add a new variable, then in the left type phones, in the right click the ${} button and select ${phone.e164}
Click the + to add a new variable.
In the left, enter text and in the right click the ${} button and select ${attr.message}
Click the Response tab.
Type in 200 and click the + button. Do the same and add 201.
Click Create to create the Trigger.
5. 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.
