Multifactor Authentication Service

Updated 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:

{Environment}

Description

test

Requests will be parsed only to ensure they are valid. No further processing will be performed.

live

Requests will be parsed and executed, and a call will occur.

{Version}

Description

1

Current version of the API

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

Request Parameter Name

Max length

Description

ClientID

4

The 4 digit ClientID supplied during enrollment

Username

20

The username supplied during enrollment.

Target

50

The target number should be in international MSISDN format (E.164 format) starting with a plus sign. The system will accept UK national formatted numbers however.

Method

10

Either VOICE or SMS depending on required call type

Code

6

The one time password to pass to the caller

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:

Status

Description

1

The request was successful.

3

The request included an invalid bearer.

4

The request was missing parameter.

5

A request parameter was not accepted.

6

The system was unable to process the request.

 

Messages used in response

Message

Description

OK

Used in conjunction with status 1.  This is a valid and accepted request.

Authorization has been denied for this request.

The bearer token was incorrect. Please check the token parameters and generation.

Missing Parameter

Used in conjunction with status 4.   A parameter was missing. (See Param string in response.)

Invalid JSON

Used in conjunction with status 5. Invalid JSON was supplied in the request.

 

Invalid phone Number

Used in conjunction with status 5. The phone number supplied was invalid. Make sure the phone number is of the correct format and length.

Invalid ClientID

User in conjunction with status 5.  The ClientID supplied was invalid.  Make sure the ClientID is four digits and correct for the service requested.

Invalid Code

User in conjunction with status 5.  The code to send the user was invalid.

Invalid Phone Number

User in conjunction with status 5. The phone number was not valid, make sure the number is valid and formatted correctly.

Rejected Phone Number

Used in conjunction with status 5. The phone number supplied was of the correct format but rejected due to being barred by the system. This will include premium rate numbers, special codes such as 118 and emergency services.

Invalid Service

Used in conjunction with status 5. The service used was not correct.

Invalid Environment Type

Used in conjunction with status 6. The environment element supplied in the URL should either be test, or live

Invalid Version Number

Used in conjunction with status 6. The version number supplied was invalid.

Throttling

Used in conjunction with status 6. The request has exceeded the configured throughput (API requests per second) limit. The request should be retried later.

Other Error

Used in conjunction with status 5 and 6. Any other error which is not specifically specified.

Params used in conjunction with status 4

Param

Description

ClientID

Missing ClientID

Username

Missing Username

Target

Missing phone number

Method

Missing Method

Code

Missing Code

  


How did we do?