Setup 2FA/MFA for Headless/Decoupled Drupal

Secure Headless/Decoupled Drupal with a robust Two Factor Authentication (2FA) using Drupal Two Factor Authentication - 2FA / Passwordless Login. This guide will help to configure Two-Factor Authentication (2FA / MFA) for Headless Drupal site. Drupal 2FA module will add a second layer of authentication to Drupal account to increase the security of site from unwanted hacks and unauthorized login attempts. The Drupal Two Factor Authentication - 2FA / Passwordless Login is available for Drupal 7, Drupal 8, Drupal 9 and Drupal 10.

Setup Drupal Headless 2FA

• Navigate to the Headless 2FA Setup tab.
• Click on Enable Headless Two-Factor checkbox to activate the Headless/Decoupled 2FA service.

• Select the authentication method of from 2FA method dropdown.

• Enter the Machine Name of the phone number field. You can click the link in Note to check available fields on Drupal site.

• Click on the Save Settings button.

Steps to integrate Headless/ Decoupled 2FA:

• Minimum requirement for integrating 2FA with Drupal :
1. Login page : Having Username and Password fields
2. OTP Page: Having OTP fields

Authenticate users by sending Username and Password

• The first step is to authenticate users by sending Username and Password to /headless/authenticate endpoint (API) so they can authenticate against the Drupal database. Once the user is authenticated successfully, OTP will be sent to registered mobile/email (depending on the configuration).

API: POST {drupal-base-URL}/headless/authenticate.
What you will send:
{"username":"xxxxx","password":"xxxxx","apiKey":"xxxxx"}
If successful, you will receive back the following response:
{"username":"xxxxx","status":"SUCCESS","message":"xxxxx","transactionID":"xxxxx","authType":"xxxxx"}


• With the following parameters:
  

PARAMETER	TYPE	REQUIRED?	DESCRIPTION
username	string	required	Entered by the user on the login form.
password	string	required	Entered by the user on the login form.
apiKey	string	required	Send the apiKey provided in the module.

Validate the user by sending OTP

• The second step is to validate the user by sending OTP (One time passcode) to /headless/login endpoint (API).

API: POST {drupal-base-URL}/headless/login
What you will send:
{"username":"xxxxx","transactionID":"xxxxx","authType":"xxxxx","otp":"xxxxx","apiKey":"xxxxx"}
If successful, you will receive back the following response:
{"username":"xxxxx","status":"SUCCESS","message":"xxxxx","userprofile":"xxxxx"}


• With the following parameters:

PARAMETER	TYPE	REQUIRED?	DESCRIPTION
username	string	required	You will get this in response to the first API call.
transactionID	string	required	You will get this in response to the first API call.
authType	string	required	You will get this in response to the first API call.
otp	string	required	You will get this in response to the first API call.
apiKey	string	required	Send the apiKey provided in the module.

Possible Errors

ERROR CODE	DESCRIPTION
400 Authentication Failed	API Authentication Failed
404 Not Found	Headless 2FA setting is not enabled. Please enable the same under the Headless 2FA Setup tab of the module.
401 Unauthorized	User has entered invalid credentials (username/password)
403 Forbidden	User has entered the incorrect OTP (One time passcode)
500 Internal Server Error	You will get 500 Internal Server Error due to various reasons, please check Drupal logs for more details.