Introduction
LogonBox supports SMS delivery via Amazon SNS, which can be used for Password Resets, Unlocking Accounts, or even just logging on to the user or admin portals.
This guide will show how you can use an SMS sent via Amazon SNS.
1. Amazon SNS Configuration
These instructions assume that you have an active Amazon AWS account. Amazon SNS is already configured for all accounts so our job here is to simply create a user and obtain some credentials so that we can use these to configure LogonBox to send SMS through Amazon SNS.
You may want to review the documentation at https://docs.aws.amazon.com/sns/latest/dg/sms_publish-to-phone.html we will be using a LogonBox task and trigger to communicate with SNS. So there is no coding required, but the task will only send individual SMS messages to phone numbers. It's not possible to publish the message to a topic or subscribe phone numbers to that specific topic.
So head over to AWS and navigate to the IAM service
Create a Policy
First we want to create a policy that allows a user to send an SMS. Click on the Policies menu and Create Policy
Add the following JSON under the JSON tab.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"sns:Publish"
],
"Resource": "arn:aws:sns:*:*:*"
},
{
"Effect": "Allow",
"Action": [
"sns:Publish"
],
"Resource": "*"
}
]
}
This policy allows the sending (publish) of an SMS but does not allow the user to publish to any SNS topic. Give the policy a suitable name and return to the IAM Service
Create a User
Now click on the Users menu within IAM and Add User
Set the username to something that describes its use, for example here I have named it "logonbox-sms-user". Click on the Programmatic access option as this user will be using the AWS API.
Now click on Next:Permissions
Click the Attach existing policies directly
Search for the policy you created earlier and click in the checkbox to select it (do not click on the policy name, it will take you out of the user creation process).
Click Next:Review and then Create User to complete the operation.
You will be presented with a further page that will allow you to download the users credentials. Download the CSV file that contains the Access and Secret Keys that will be used to communicate with the AWS API.
2. Add SNS keys to LogonBox configuration
Open the CSV file downloaded from Amazon in the previous step and get the two keys.
In LogonBox, go to Authentication Flows->Authentication Options in the left menu, then click the SMS tab.
Change the Provider to Amazon SNS.
Whilst you are on this page you can also set options such as how LogonBox prompts to enter the code and what message is sent out to users as well as the Default Country Code.
Default Country Code is the default location of your users. If a user's phone number does not contain an International Dialing Code for their country it will default to this value for this selected country.
Note that the Default Country code is a selector box. Either start typing the country you want and choose from the list that appears, or type * to get a full list and select from there.
Click Apply when done.
Now navigate to Messages->Settings and select the SMS(AWS) tab.
Enter the Access Key and Secret Key here that was generated in your Amazon account, set the nearest region to you.
You can also set a Sender ID here which identifies the SMS sender to the user on their phone. This must be no more than 11 characters.
Click Apply.
3. Authentication Scheme
At this stage, it is important to note that you can apply different authentication flows for several different types of logon, including: User Logon, Password Reset, Account Unlock, Windows Logon 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 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 the existing green module with the SMS one. 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 Apply.
There are some further configuration options regarding how the one time code is generated. If you need to change anything, navigate to Authentication Flows->Authentication Options and click the SMS Code tab. As you will be sending messages to mobile devices, it might be a good idea to set Symbol Chars to 0 to remove the difficulty of entering these characters from a mobile keyboard. Click Apply to save the changes.
4. 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, assuming you kept the default option on the SMS page for Use Directory Phones.
LogonBox will automatically prompt a user to validate their mobile number the first time they log in to My Account.
For example, this user has just entered their username and password and didn't have a mobile number stored on their account yet.
The user confirms their country and adds a phone number and clicks Next.
An SMS should then be sent to the user, who enters the code on this screen and clicks Next.
The user's mobile number has now been validated. They can remove this number or add a new number in their My Credentials->SMS Numbers menu.
5. 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 you see a confirmation that your password has been reset.
