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 sms77 (https://www.sms77.io/en)
Create sms77 account
If you wish to use sms77 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 sms77 web site.
You should receive an Email from sms77 to confirm your account.
Configure sms77
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 Developer menu on the left menu, then the plus on API Keys.
Give the key a label, choose Live environment and click Save.
Make a note of the API key that is then displayed as this will be needed for the LogonBox configuration.
If you click the Key, it will copy it to the clipboard.
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 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.
In the left text box, type: authorization
In the right box, type Basic followed by a space then your API key: i.e Basic 4AYJBLSUbIWhnR1pFQMAcr7TNNcKZEPQzVfhdTC
Click the HTTP Form tab.
Set the Request Method to POST.
For the URL, enter: https://gateway.sms77.io/api/sms
For Variables, in the left type to, 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.
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.
