Multifactor Authentication Service

Updated 3 years ago by Support Author

Introduction

This product provides various options for multi factor authentication adding an additional layer of security when users log into systems.

Two methods can be employed for this. The first option is to a send code to user, via SMS or voice call, which they can then input into your system. The second send a voice call to the user and collects a code they enter which is then passed back to a specified call back URL on your system for processing.

This product provides back end set up screen and an API to receive MFA requests.

Set up

Once access has been provided to the service it will be found under the Call Handling section in the portal.

Select service set up to begin setting up a new service.

Click create new service to begin set up.

Set up Fields

API Username

This is the username that will be used in the API and maps to the field Username.

API Password

This is the password that will be used in the Bearer token as part of the security requirements for this API.

Description

This is the user friendly name of the service.

SMS Originator

This is for use with SMS version of the send code version. The originator can be either 11 alphanumeric characters or 14 numeric. The default originator is SecureCode

SMS Message

This is the message that will be sent out in response to an SMS API request. Use the [code] modifier in the message to signify where the code will be inserted into the message. Messages can be a maximum of 160 characters.

Call Originator

In voice calls this is the CLI that will be presented to the person receiving the call. This should be a phone number which is connected to the organization making the call. If required, please discuss with your account manager options for an information line you can present explaining what the call was regarding.

Voice Method

This parameter controls the type of OTP call made.

The two options are:

Say OTP: This method will call the user and say a code to them

Collect OTP: This method will call a user and collect a code which will then be passed back to a call back API

Audio

The following parameters control the audio used in the service. This can either be the default system audio, or user provided audio via the Audio Database. Please ensure any custom prompts fit the intended meaning of the standard system prompts.

Intro Audio

This is the wording for the introduction. Standard system wording is: Hello, this is your security authentication call.

Code Is Audio

This is the wording for initial playback of the code. Standard system wording is: To confirm you wish to gain access please enter the following on time password on the website.

Repeat Audio

This is the wording for repeating the code. Standard system wording is: That code is....

Outro Audio

This is the final prompt played to the caller. Standard system wording is: Thank you and goodbye

Once all parameters have been set click the green "Add New Service" button to create the service. If there are no errors then a service created message will be displayed, otherwise there will be an error message related the problem.

Service Testing

The service can be tested both via the API or the provided testing page. To use the test page select service text from the menu:

To test select the desired service to test from the Service ID drop down.

Target Number: This is the number that should be contacted in the service

Method: This is either Voice Call or SMS.

Code: This will be the code to give to the user

Once the parameters have been entered click the green Generate Post button. If there are no errors the system will generate both the header and body which would be needed in API request to generate a call. This page can be used to compare programmatically generated parameters against known values.

Use the Red test API and Service to test the service via a web call to the API, use the yellow Test Service button to generate a call directly.

In the response section will be the result of the request and the unique ID for that request.

Search Logs

To view logs and result of any requests select search logs from the menu:

This will searching for results on a given day or by target number.

API Requests

This service will be used to provide an extra layer of security when a customer is logging into a service.

The API is very light-weight, using JSON over HTTPS in a REST-like manner. All operations must be made as POST requests. No other HTTP methods are used.

Once a validated request has been received the system will contact the target and the flow will be as per the setup on the portal.

It is the legal responsibility of the client to get consent from the end user for contacting them in this manner. The user consent must be stored by the client and it must be possible to audit the consent information.

API Endpoint

https://webfarm.telecomstats.co.uk/MFAAPI/api/{environment}/{version}

{environment}, {version} are defined as follows:

None breaking changes can be made to the current version of the service (such as the addition of extra optional parameters). Any change which would cause a breaking change will be handled using the versioning parameter.

Example end points:

Live, version 1

https://webfarm.telecomstats.co.uk/MFAAPI/api/live/1

Test, version 1

https://webfarm.telecomstats.co.uk/MFAAPI/api/test/1

Request Header

Content type header

The Content Type header must be set correctly for all POST requests:

Content-Type: application/json

Authorization header

A SHA512 bearer token is used use for authorization in each request and is comprised of various elements of the request and the API password created during set up.

Authorization: Bearer azpa0miERSoSqL19GI3lQQrUny/2yU0m/ZAaIEBwZLLhTeuGrSyZmW1Xixfk1oN/vwaMTTySFAknc37sVitagg==

The token is created use parameters from the request as follows:

{clientId}{username}{password}{target}{method}{code}{date}

where date is in the format ddYYYYMM eg 10th November 2020 is 10202011

Below is an example in C#

// requires System.Security.Cryptography;

HashAlgorithm sha = SHA512.Create();
int clientId = 1000;
string username = "Demo";
string password = "QG$7OuI&q2y575P";
string target = "07912345678";
string method = "VOICE";
string code = "123456";
string date = "10202011"; // ddYYYYMM

string plainData = $"{clientId}{username}{password}{target}{method}{code}{date}";

// plainData = "1000DemoQG$7OuI&q2y575P07912345678VOICE12345610202011"

byte[] hashedData = sha.ComputeHash(Encoding.UTF8.GetBytes(plainData));
string hash = Convert.ToBase64String(hashedData);
// hash = "azpa0miERSoSqL19GI3lQQrUny/2yU0m/ZAaIEBwZLLhTeuGrSyZmW1Xixfk1oN/vwaMTTySFAknc37sVitagg=="

Request Body

The request body must include the following parameters in a JSON payload

Example request:

{
    "ClientID":1000,
    "Username":"Demo",
    "Target":"07912345678",
    "Method":"VOICE",
    "Code":"123456"
}

​Response Codes​

​The endpoint in this API does not use HTTP status codes for returning the result of a request. Following processing of a request, the HTTP status code returned will always be 200. The response body will contain a JSON structure with a 'Status' and 'Message' that represents the result of the request.

Status is a JSON integer with a maximum value of 99. (Not all values are currently used and are reserved for future updates.) Message is a JSON string with a maximum length of 50 characters.

Status 4 has an additional JSON string called Param which is used to signify which parameter is missing, and which has a maximum length of 50 characters.

The possible values are:

Messages used in response

Params used in conjunction with status 4

How did we do?

Related Articles

• Portal Multifactor Authentication
• Portal Multifactor Authentication - Reset QR Code
• Service Configuration