Introduction
LogonBox supports 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 via Email, but this guide will show how you can use an SMS to Email gateway to send logon passwords to your users' mobile phones.
For this example, we will be using a service run by Kapow (https://www.kapow.co.uk)
1. Kapow website configuration
Assuming you already have a Kapow account with SMS credits available, log on to their website at https://www.kapow.co.uk.
Navigate to SMS Centre.
Then Sending Options.
In the Trusted Email Addresses section, type in the email address that we'll be identifying as when we actually send messages and click Add.
2. SMTP settings
You will now need to configure your LogonBox to use your own SMTP server to relay emails through.
Refer to this article (for cloud hosted) or this article (for on-prem) to discover how to do this.
Ensure you set the From Address to the same you used for the trusted email address on Kapow.
3. Authentication Scheme
At this stage, it is important to note that you can apply different authentication flows for many different types of logon, uncluding: User Logon, Password Reset, Account Unlock and Admin Logon.
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->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.
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.
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.
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.
4. Create a Trigger to send the message
Now navigate to Triggers and click Create.
Give the new trigger a name such as Send OTP SMS. In the event start typing SMS and select the SMS Generated event when it appears.
Set Triggers On to Success. For Triggers Task, start typing Send Email and select it from the list.
Now we need to set the content of the email that is sent out in the format required by Kapow. As we already set a trusted email address in the Kapow account, it doesn't matter what appears in the body of the email, the text message should all be in the Subject line.
Click the Plain Message tab and in the Subject, type 'Your one time password is ${attr.sms}' (without the quotes). Feel free to alter the message as required, but do not leave out the ${attr.sms} as this will be replaced with the actual password that gets generated.
Now we need to add a new email address which will be based on the user's mobile number as this is the format expected by the Kapow service.
Click the Delivery tab and in the To section, first click the ${} button and select ${phone.e164}. When that appears in the text field, type in @kapow.co.uk. Click the plus icon to add it, then click Create to finish the trigger.
5. Setting mobile numbers for users
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 One Time Password, you are then allowed and prompted to change your password.
Finally, confirmation that your password has been reset.
