Multi Factor Authentication - User Guide
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 = "077XXXXXXXX";
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":"077XXXXXXXX",
"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 |
