Two Factor Authentication

An authentication factor is a category of security credential used to verify a user's identity and authorization before allowing that user to gain access to their account, send communications, or request data from a secured network, system, or application.

Two-factor authentication (2FA) is a security process where users must provide two different authentication factors to verify their identity and access their account. This process ensures better protection of a user's personal information, credentials, and other assets, while also improving the security around the resources the user can access.
Certainly, two-factor authentication provides a higher level of security than authentication methods that rely on only one authentication factor (single-factor authentication), where the user provides only one factor (usually a password or PIN). A 2FA method would require a user to provide not just a password or a PIN, but a second factor, ranging from a biometric factor (a facial, retinal, or fingerprint scan) to a possession factor (a one-time use code sent to a smartphone known to be in a user's possession).

Now, 2FA adds an additional layer of security to the authentication process by making it harder for attackers to gain access to a person's devices or online accounts because knowing the victim's password alone is not enough to pass the authentication check. Two-factor authentication has long been used to control access to sensitive systems and data, and online service providers are increasingly using 2FA to protect their users' credentials from being used by hackers who have stolen a password database or used phishing campaigns to obtain user passwords.

Managing Two Factor Authentication

A two-factor authentication code is a one-time code generated to prove a user's identity when they try to access an online account or system. The code would be sent via text message or by an automated phone call to a phone number associated with the user. Upon entering the two-factor authentication code, the user gains access to their online account.

📘

NOTE

These codes often expire after a short amount of time if not used.

The API provides functions to create a new two factor configuration (code generator), request a new two factor authentication code and provide a validation status for that specific request. Additionally there are functions to get a list of code generators previously configured. Cancel and verify status code is currently supported via API.

Our RESTful API lets developers easily integrate Two Factor Authentication into their solutions.

Through the following diagram we explain the 2FA security process between your Project and Digital Engagement API:

1. User enters the phone number into the client’s application (mobile or web)

2. Application sends a request for the code with the user’s phone number to Platform . That is, initiate Two Factor Authentication Process by sending the Mobile Number.

3. Platform proceeds to create a code generator which helps to configure the code that will be sent to the end user.

4. Platform delivers the SMS with the security code to the final user.

5. Platform generates the request ID, and sends the request ID back to the application.

6. User enters the received security code provided by Platform into the application.

7. Application sends the verification request with the security code and request ID to Platform .

8. Validate if the end user entered the correct code or not. That is, if there is a match between the request iD that Platform provided to the application and the security code, the user will be considered as a valid user, otherwise will be considered as a invalid user.

9. Platform verifies the received code and sends the response (validation status) to the application.

The steps to configure, send and verify a code are the following:

• Configure a code generator

• Request and Send the code (via SMS or Email) to your customers

• Validate User

Creating Code Generator

Code Generator is a security feature for your Application used with two-factor authentication. You can add an authentication factor linked to a channel (SMS or Email for example). When a user signs up or logs into your application a numeric code is sent to their mobile device either via SMS, email or push notification or through an authentication app. For this reason, the first step is to create the code generator and configure the code that will be sent to the user.

At this point, you need to define the code length, the expiration time of the code, the delivery channel in which the code will be sent and the message body with the code placeholder that is sent to the end user.

You are currently able to delivery the security code through two delivery channels:

• SMS : SMS is the most popular channel for two-factor authentication (2FA). That's because most people can receive text messages and onboarding is seamless.

• Email : One time passcodes (OTP) sent to email can help protect your users if their password is brute-forced or phished. Like SMS, it doesn't require downloading another app so onboarding will be quick and seamless.

Code Generator works on your mobile device as long as you have a valid number to receive text messaging (SMS) or an Internet connection for receiving PUSH and Emails and it can be reused as many times as you need.

When you create a Code Generator, the request body contains the following data:

HTTP Request : POST /v1/2fa

{
  "codeLength": 6,
  "expirationMinutes": 10,
  "channels": [
    {
      "type": "SMS",
      "shortcode": "1234",
      "message": "your verification code is {0}"
    },
    {
      "type": "EMAIL",
      "from": "[email protected]",
      "subject": "Verification code",
      "message": "your verification code is {0}"
    }
  ]
}

The parameters presented in the request body example when creating the Code Generator are the following:

When you have created the code generator, the response body contains the following data if you configured the code generator with the SMS delivery channel for example:

{
  "meta": {
    "timestamp": 1618100570108,
    "transactionId": "1beeee1f-4fcb-471d-af9b-d74413e3d28f"
  },
  "data": {
    "id": 78,
    "codeLength": 6,
    "expirationMinutes": 10,
    "channels": [
      {
        "shortcode": "1234",
        "text": "your verification code is {0}",
        "type": "SMS"
      }
    ]
  }
}

We only describe the additional parameters that are generated when making the request.

To consult each description parameter (not additional parameters) displayed in the response body example, go to the parameters presented in the request body example when creating the code generator.

The additional parameters presented in the response body example when creating the code generator are the following:

Getting Code Generator

When the Code Generator is previously created, you proceed to get the specific data from a single code generator.

HTTP Request : GET /v1/2fa/{id}

To get a code generator, you need to provide the unique identifier of the code generator you want to retrieve the information.

Generating and Sending Security Code

After setting up the code length, expiration time, delivery channel where the code will be sent, shortcode and message, you can start generating and sending via SMS or Email the security code to the provided destination address. As long as the User has a mobile phone or an email defined you may send the user a code.

To generate a security code, you only need to specify the code generator id you want to use, the channel where you want the code to be sent and the phone number or email address to whom the 2FA message will be sent.

Once the code has been generated and sent to the recipient, you will be provided with a request_id and the user will be provided with a security code that he requested.

📘

NOTE

Each code is only sent through one delivery channel.

In case the user does not receive the requested code, he can request a new code on a different delivery channel. For example, this endpoint allows you to send the code via SMS but if the user doesn't receive the code, you can define the Email channel from the channel parameter to send the new code via Email to the receiver (user).

Before sending the code via SMS or Email, you need to create the code generator to configure the SMS or Email delivery channel.

The User must already have a valid mobile phone or email address for this to succeed.

HTTP Request : POST /v1/2fa/{id}/codes

When you request a new two factor authentication code, the request body contains the following data:

{
  "channel": "SMS|EMAIL",
  "receiver": "1234|[email protected]"
}

The parameters presented in the request body example when generating the security code ode are the following:

When you generated the security code, the response body contains the following data:

{
  "meta": {
    "timestamp": 1618181833535,
    "transactionId": "a9e0e8d4-8bb0-46f2-9a1c-955f9c"
  },
  "data": {
    "requestId": "1e24a4d6-e2fb-317d-a79e705"
  }
}

The parameters presented in the response body example when generating and sending the security code are:

To generate and send the security code to the user, you need to provide the unique identifier of the code generator you want to use.

Validating User

Once the code has been generated and sent to the user via SMS or email, you proceed to validate the user.

When the user enters the security code to your application, you can carry out the following actions :

• Verify the security code to validate the user.

• Cancel the security code.

• Check the Status of the security code.

In order to perform each action as mentioned above, you need to provide the request ID and the security code of the user once he entered it into your app.

HTTP Request : PATCH /v1/2fa/{id}/codes

When you want to verify the user, cancel the code or check the status code, the request body contains the following data:

{
  "action": "VERIFY|verify|CANCEL|cancel|STATUS|status",
  "requestId": "HFTHJDL445HDBASL",
  "code": "1234"
}

The parameters presented in the request body example when validating the user are the following:

When you verified the security code, the response body contains the following data:

{
  "meta": {
    "timestamp": 1597166699457,
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
    "explain": "valid code"
  }
}

The parameters presented in the response body example when validating the user are the following:

To validate the user, cancel the code or check the status code, you need to provide the unique identifier of the code generator you want to use, the security code and the request Id.