Introduction
LogonBox supports the delivery of One-Time Passwords for any of the supported authentication flows. This type of authentication is often used to allow users to reset their own passwords, by sending a one time, unique code that is sent to the user via an email to allow them to login and reset their password.
Its often a requirement that this password be sent by SMS to a users mobile phone. This is fully supported within LogonBox but requires specific configuration depending on the SMS provider you choose to use.
We have documented integration with a number of SMS providers. If you choose to use one of these you can follow the links below.
If your chosen provider is not supported above, you can of course contact our support team who will help you through the configuration for your chosen provider. Your provider will either need to support sending SMS via an email to SMS gateway, or through a HTTP gateway.
Option 1 - Using an Email Gateway
If your SMS provider supports sending SMS via an email gateway then you will likely have to consider the following configuration. IMPORTANT these instructions are generic and may not work with all providers. If you have any doubts or issues please contact our support team who can advise you the best way to setup any provider we have not already documented.
SMTP Settings
By default, your LogonBox will use our default pre-configured email server. It's likely that your SMS email gateway will require an email from a trusted address. If this is the case you will need to configure your SMTP settings to send email through your own SMTP server. Refer to this article to discover how to do this.
Editing the OTP Generated Message Template
LogonBox has a default Message template setup to send the one-time passwords directly to the users email address. It's possible that you can modify this template to send to the email gateway. You can edit the One Time Password Generated message resource under Business Rules -> Messages and set the body or subject to the values requried by your SMS to email gateway.
You should then navigate to the Delivery tab and..
- Set "Deliver To" field to ONLY_ADDITIONAL this will ensure that the email will only ever be sent to any email you place in the "Additional Recipients" field below it.
- Enter the SMS to email gateway address in the "Additional Recipients" field
- Set the "Reply-To Name" and "Reply-To Email" fields to the trusted email address you setup with your SMS to email gateway.
Once you have setup this to your requirements, click Update and proceed to test your authentication flow.
Option 2 - Using a HTTP Gateway
LogonBox supports a flexible event system called triggers that allow you to execute tasks in response to system events. With practically every action in the system generating an event, we can utilise this mechanism to capture the OTP Generated event and send the password via a HTTP request using one of the HTTP tasks.
Disable OTP Email Template
The first thing we should do is navigate to Messages -> Message Templates and locate the One Time Password Generated email and edit it. Under the Options tab, locate the "Enabled" field and turn off the switch and finally click Update button.
This will prevent the OTP authentication mechanism from sending out an email. We can now attach a task to the OTP Generated event to send our password via HTTP to the SMS provider.
Create Trigger
Navigate to Triggers and click Create. Add a suitable name for later identification, for example I've used "Send OTP via SMS".
Then in the "Event" field start typing OTP and allow the system to popup a list of matching events. You will find the OTP Generated event, select this.
This will add another two fields underneath the Event field. You should select "Success" for the "Triggers On" status. You only want to do this on successfull events.
In the "Triggers Task" field, start typing HTTP and you will be presented with two options. Its probably likely that you will need to use a HTTP Form task. This task supports sending HTTP POST or GET requests to remote servers.
The form will now populate with more settings.
You can ignore the Conditions tab. We just want to send the HTTP request everytime the event is triggered. How you complete this form however is dependent on what your SMS provider's HTTP gateway requires.
If you need to set any specific HTTP headers you can do so by adding entries under the Headers tab. Its important to note that these will be defined by your SMS provider in their documentation. As an example, let's imagine that the provider requires an authentication header "X-SMS-Authentication" and gives you a token value to use that uniquely identifies your account. We would enter the header name in the first field, and the header value in the second.
The next Tab where you will need to enter some information is the HTTP Form tab. You need to choose the type of HTTP request, again this will be defined in your SMS provider's documentation. It will either be a POST or a GET request.
Enter the URL of the HTTP request as stated in the SMS provider documentation.
You then need to configure any variables. As an example we will pass the text of the SMS message in a "text" variable, and the "phone" number it should be sent too.
Finally, to ensure we have some error handling. In the Response tab we should add the HTTP status codes that indicate a valid response from the server. Typically this will be the value "200". Please consult your SMS provider's documentation for this value.
Now save the trigger by clicking Create. You can now proceed to test and verify your trigger by attempting to use the OTP authentication. If you receive any errors or have problems then check the Audit Log as the HTTP task will output any issues in a failed event.
Please contact support if you need any help with any of the elements documented in this article.
