Two Factor Authentication

An authentication factor is a category of security credentials 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. 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, Email or WhatsApp) 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, Email or WhatsApp). When a user signs up or logs into your application a numeric code is sent to their mobile device either via SMS, Email or WhatsApp 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 deliver the security code through three 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.

• WhatsApp: If your app offers users the option to receive one-time passwords or verification codes via WhatsApp, you must use an WhatsApp Authentication Template.

  📘

  NOTE

  Before creating a code generator, you need to create a Whatsapp Authentication Template. For more details go to the “Two factor Authentication (WhatsApp)” use case to know how to integrate WhatsApp with two Factor Authentication.

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}"
    },
    {
      "type": "WHATSAPP",
      "address": "181920",
      "templateId": "242528",
      "placeholder": "code"
    }
  ]
}

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 SMS, Email, and WhatsApp in a single API request:

{
  "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"
      },
      {
        "subject": "Verification code",
        "from": "[email protected]",
        "text": "your verification code is {0}",
        "type": "EMAIL"
      },
      {
        "placeholder": "code",
        "address": "181920",
        "templateId": "242528",
        "type": "WHATSAPP"
      }
    ]
  }
}

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:

Generating and Sending Verification 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.

🚧

WARNING

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 or another channel but if the user doesn't receive the code, you can define the WhatsApp channel from the "channel" parameter to send the new code to the receiver .

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

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

In this API call, you need to provide the unique identifier (“data.id”) of the code generator previously created.

{
  "channel": "SMS|EMAIL|WHATSAPP",
  "receiver": "+525500000000|[email protected]|+525500000000"
}

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

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

{
  "meta": {
    "timestamp": 1618181833535,
    "transactionId": "a9e0e8d4-8bb0-46f2-9a1c-955f9c"
  },
  "data": {
    "requestId": "14r578t-a257-u789-e347920"
  }
}

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

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 verification code that requested.

Validating Verification Code

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

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 this example, we'll solely verify the verification code.

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

In this API call, you need to provide the unique identifier (“data.id”) of the code generator and the unique identifier (“data.requestId”) of the request previously created.

Prior to validating the user, it's necessary to initially verify the status of the verification code.

{
  "action": "status",
  "requestId": "14r578t-a257-u789-e347920"
}

The parameters presented in the request body example when verifying the status of the verification code are the following:

When you have verified the status of the verification code, the response body contains the following data:

{
  "meta": {
    "timestamp": 1707243156412,
    "transactionId": "6ae15fa5-1e97-45dc-be65-275f51967fef"
  },
  "data": {
    "id": 534,
    "userID": "+525500000000|[email protected]|+525500000000",
    "token": "135385",
    "requestID": "14r578t-a257-u789-e347920",
    "expirationDate": "2024-02-06T01:44:37.020949",
    "validationDate": null,
    "validationChannel": "SMS|EMAIL|WHATSAPP",
    "status": "PENDING"
  }
}

The parameters presented in the response body example when verifying the status of the verification code are the following:

Because the verification code is in “PENDING” status, we proceed to validate the code.

📘

NOTE

In this API Call, the user needs to enter their verification code to valid the code.

We acquired that code from the previous request to provide you with a clearer understanding of its status and validation.

{
  "action": "verify",
  "requestId": "14r578t-a257-u789-e347920",
  "code": "135385"
}

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

When you have validated the code, the response body contains the following data

{
  "meta": {
    "timestamp": 1707252519688,
    "transactionId": "42421f-96f60",
    "explain": "valid code"
  }
}

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