Secure your Headless Drupal Website with Robust 2-Factor Authentication

Headless/ Decoupled 2fa

While traditional CMS architecture has been the industry standard for quite some time now, lately there have been a lot of major players who are now looking for increased flexibility and scalability.

This is achieved by using a Headless or Decoupled CMS architecture.

We have developed a novel solution for adding a 2-Factor Authentication layer into your Headless Drupal based website.

Before we get into the nitty-gritty, here is what it means to have a Headless Setup.

One way to visualize traditional website setup, would be to imagine a single crucible, wherein all the Content, Images, HTML and CSS files are kept. This entails, it is impossible to reuse the content as it gets blended in with the code.

Whereas, The design of Headless systems is in such a way that the content is free from any shackles to an output, i.e., it is decoupled from any output like web page rendering. Instead, the content is sent over as data over an API.

Now, the breakdown of the actual solution.


Front End:

ReactJS — 2 Pages

  • Page 1, is your run-of-the-mill Login Page, wherein you would type the Username and Password.
  • Page 2, is the page wherein you would enter the received OTP for verification.

Back End:

APIs Involved:

Backend API (Drupal)

  • Authentication API
  • Login API

Server APIs (miniOrange)

  • User Search API
  • User Create API
  • Update 2FA API
  • Challenge API
  • Verify 2FA API

All these APIs are custom-built from scratch, to achieve the first ever 2FA authentication on a Headless Drupal System


Stage 1: Login

The login process starts from the end user’s side. The user types in the Username and Password in the front end, in this case the ReactJS page.

Once the sign-in process begins, the Authentication API is invoked, (/headless/authenticate). This sends the user input, i.e. the username and the password, to the Authentication Endpoint on the Drupal site in JSON format.

{“username”:” xxxxx”,” password”:” yyyyy”}

Stage 2: User Check

Back at the Drupal site, upon receiving the input from the Authentication API, the information is then used to check whether the credentials match with any of the existing Drupal users, i.e. it checks whether the provided user information is legitimate or not.

If either of the Username or Password fails authentication, then an error message is sent back to the ReactJS front end and the user is prompted to input the correct/valid credentials.

After the user is successfully authenticated, the User Search API is invoked on the miniOrange Server.

As with any binary problem, there arise 2 possible scenarios.

2.1 Registered User (User is found in Search API)

If the User attempting to log in, is already registered at the miniOrange Server, then it proceeds to call the Challenge API. The Challenge API invokes the configured 2FA method. Once invoked, an OTP is sent via the selected method i.e. via SMS, Email, Phone Call or a combination of multiple methods.

2.2 Unregistered User (User is not found in Search API)

Whereas, If the User attempting to log in, is not registered, then a User Creation API is invoked. The user is created based on the username and email ID, and the 2FA setup is configured based on the preset settings by the admin.

Once the user is created, then the process is similar to the Registered User scenario. The challenge API is invoked and OTP is sent via the selected method i.e. via SMS, Email, Phone Call, or a combination of multiple methods.

Upon successful invocation of the Challenge API, a JSON response is sent back to the Front End.

{“username”:” xxxxx”,“status”:” SUCCESS”,“message”:” xxxxx”,“transactionID”:” xxxxx”,“authType”:” xxxxx”}

Stage 3: OTP Verification

At the front end, the user types in the received OTP. After which the Login API is invoked, and the entered OTP along with other user identifiers is sent back to the Drupal site in a JSON format.

{“username”:”xxxxx”,”transactionID”:”xxxxx”,”authType”:” xxxxx”,”otp”:”xxxxx”}

At the Drupal site, the Verification API is called after receiving the JSON input with the OTP.

Again, as a binary decision, either the typed-in OTP is valid or it isn’t.

3.1 Correct OTP

If the OTP is correct, then a success response is sent in a JSON format, which also has the User Information from the Drupal site i.e. User ID (UID), Assigned Roles, and Attributes.


Note: userprofile includes UID, Roles, Attributes etc

3.2 Incorrect OTP

If the entered OTP is incorrect, then an error message is displayed for the user, and the user is prompted to type in the OTP again. After resubmitting, the OTP verification stage is repeated till the OTP is successfully verified.

After successful verification, a session is created on the Back End System, i.e., Drupal. And a ‘success’ response is sent back.


Now for all the graphical learners out there, here is the flow for the entire authentication process.

The first one, is for when the user is registered, i.e. found in the User Search API

User Found
Fig 1.1 Login Flow for a Registered User

And the alternative, when the user is unregistered, i.e. user is not found in the User Search API.

User not found
Fig 2.1 Login Flow for an Unregistered User

Many websites, which have to maintain a fresh, modern look, undergo a redesign every few years. This would be much easier with a decoupled system. Having a robust system secured with 2-Factor authentication which can undergo numerous UI revamping is something that everyone in the industry would be moving towards.

Now, you can do just that. Securing your decoupled or headless system with a state of the art 2FA module.

Related Modules:

miniOrange Drupal LDAP Module

miniOrange Drupal SAML Module




miniOrange Single Sign-On (SSO) & Multi-Factor Authentication (MFA) solution for more than 5000+ pre-integrated applications

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

The Iliad in Javascript

Building CI/CD for React Static Web Apps Service Using Azure DevOps


How to Create a Sleek Preloader Animation Using GSAP Timeline

#Trading is not an easy feat, but with @VSTMEX, we ensure that when you SIGNUP, we provide lessons…

Introducing Vue Native

Quick hacks for Stacks (featuring: a review on Queues)

A stack of cinnamon swirl pancakes. This can serve as a mental model for a Stack data structure.

But what is Synchronous and Asynchronous programming?

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
MiniOrange Inc

MiniOrange Inc

miniOrange Single Sign-On (SSO) & Multi-Factor Authentication (MFA) solution for more than 5000+ pre-integrated applications

More from Medium

Laravel 9 — full text index

Apply Drupal 9 patches with composer

Codeigniter 4 — Hide / Remove public folder and index.php from URL

Setting 🆙 Cloudflare Email fo