Skip to main content

Multi-Factor Authentication

Overview

Multi-factor authentication (MFA) is a security enhancement that requires users to verify their identity through multiple verification methods. By adding layers of authentication, MFA provides robust protection against unauthorized access, ensuring that accounts remain secure even if one factor is compromised.

This document provides an overview of MFA concepts and detailed step-by-step guidance for implementation. It also addresses advanced features like step-up authentication, backup codes, and custom MFA configurations.

LoginRadius supports the following authentication methods for MFA:

  • SMS OTP: A text message containing a one-time passcode (OTP) is sent to the consumer to be consumed on your website after the consumer has passed the traditional login procedure.

  • Time-Based OTP: The user receives an OTP via an Authenticator App installed on their mobile device to be consumed on your website after the user has passed the traditional login procedure.

  • Email OTP: The consumer receives a verification code on their email ID. They need to use this verification code as 2FA to log in to the website.

  • Security Questions: The consumer needs to set up a security question/answer at the time of registration or first login and use that answer as 2FA to log in to the website

  • Push Notification: This method sends server messages to a user's device, often used for authentication. The user receives a QR code notification, which they scan with their app to verify and add security to the login process.

  • Passkey: The MFA Passkey method provides an additional layer of security for user authentication by enabling multi-factor authentication through passkeys. These APIs support passkey registration, verification, and resetting for MFA purposes.

  • Backup Codes: Backup Codes are vital for MFA workflows, providing a fallback when users can’t access their second factor (e.g., unavailable phone). Users generate codes in advance for uninterrupted access. Below is an example of the typical Backup Code workflow.

  • [Duo Authentication:] Duo MFA enhances security with passwords and tokens, offering flexible options like push, SMS, calls, and hardware for seamless protection.

To support developers and administrators who may be unfamiliar with Multi-Factor Authentication (MFA) concepts, the following glossary provides clear definitions of key terms:

  • Authentication Factor: A category of credentials used to verify an individual's identity, typically classified as something you know (e.g., password), something you have (e.g., security token), or something you are (e.g., biometric data).
  • Step-Up Authentication: An additional layer of authentication is required to access sensitive resources or perform high-risk actions.
  • Passkey: A secure and phishing-resistant authentication method based on public-private key cryptography.

Configuration

Enabling MFA is an important step in enhancing your application's security. It helps protect against unauthorized access and provides a layer of verification for your users. The MFA Authentication section in the LoginRadius dashboard allows you to configure multi-factor authentication for your application users. By default, MFA is disabled on your LoginRadius site.

There are two options for configuring MFA:

  1. Optional:
    • Enabling this setting will allow your users to decide whether to enable or disable Two-Factor Authentication when logging in.
    • Use Case: In business cases where adding multi-layered security is not a must, it is nice to have.
  2. Required:
    • With this setting, users will be mandatorily required to authenticate twice before logging in.
    • Use Case: In business scenarios where verifying the user identity is necessary, such as in the banking, government, and healthcare industries,
  1. In the LoginRadius Dashboard, navigate to Multi-Factor Authentication, which is available under the Security section, and click on the MFA setting to redirect you to the configuration section.
  2. Select the desired MFA flow in the configuration section - "Optional" or "Required".
  3. Click "Save" to apply the changes.

Once MFA is enabled, users will be prompted to configure their preferred MFA method (e.g., SMS, Authenticator app) the next time they log in.

The default method will be SMS OTP (One-Time Password) to enable MFA for the first time. If MFA was previously set up with another method, it will continue to use that method by default. Once you set your desired flow, you will be prompted to enable the MFA Factors that suit your use cases, described below:

Backup Codes

Backup codes are essential in multi-factor authentication (MFA) workflows, providing a fallback option for customers who cannot use their second factor. For example, if a customer's phone is broken and cannot receive SMS messages for authentication, they can use one of their previously generated backup codes. Below is an overview of a typical backup code workflow:

Generating Backup Codes

After completing an MFA login, customers can generate backup codes. These can be created using either the MFA Backup Code by Access Token or the MFA Backup Code by UID endpoints.

Using Backup Codes

If the customer cannot complete an MFA login (e.g., their phone is unavailable), they can use one of their previously generated backup codes. Each backup code is valid for a single use. The customer submits the code to the MFA Validate Backup code endpoint. Upon successful validation, the customer is logged in.

Resetting Backup Codes

To allow customers to generate new backup codes, you can reset the existing ones using either the MFA Reset Backup Code by Access Token or the MFA Reset Backup Code by UID endpoints.

Implementing this workflow provides a secure and user-friendly solution for scenarios in which the standard second factor is unavailable.

You can seamlessly transition between different MFA methods without resetting your settings. For instance, you can disable an existing MFA method and easily activate a new one.

Integration Guide

This guide provides a detailed walkthrough for integrating robust and secure Multi-Factor Authentication (MFA) in your application using LoginRadius. It covers back-end workflows, front-end customization, and post-login management to ensure a seamless and secure user experience.

Back-End Integration

The back-end integration handles MFA logic, enabling secure communication with the LoginRadius platform. However, certain MFA APIs are intended to be called from the browser for front-end workflows. This section clarifies the distinction and provides options for implementing MFA using LoginRadius.

Using LoginRadius SDKs

  • LoginRadius SDKs simplify integration by offering pre-built libraries for popular programming languages.
  • SDKs streamline communication with LoginRadius APIs and include built-in methods for MFA workflows.

Using REST APIs

For greater flexibility and precise control over your workflows, you can use REST APIs. LoginRadius provides dedicated API documentation for each authenticator type:

  1. Authenticator MFA API: Explore comprehensive endpoints for managing MFA through authenticators.
  2. SMS Authenticator API: Enable and customize SMS-based multi-factor authentication.
  3. Email Authenticator API: Configure and manage email as an additional security layer.
  4. Security Question Authenticator API: Use security questions to provide an added layer of verification.
  5. Push Notification Authenticator API: Integrate push notifications for a modern, user-friendly authentication experience.
  6. MFA using Passkey: Enhance user login experience with seamless Passkey integration.
  7. MFA using Backup Codes: Backup codes offer customers a recourse if they can't provide their second authentication factor.

Here are the sample steps to implement MFA using APIs:

1. First, enable Multi-Factor Authentication (MFA) in your LoginRadius Admin Console and select your preferred authentication method.

2. Set Up First Factor Authentication Implement the first authentication factor using one of these APIs:

Example API Call (cURL):

curl -X POST 
'https://api.loginradius.com/identity/v2/auth/login/2fa?apikey=&loginurl=&verificationurl=&emailtemplate=&fields=*' \
-H 'Cache-Control: no-cache' \
-H 'content-Type: application/json' \
-d "{ "username": "Username of the user", "password": "Password of the user", "securityanswer": { "db7****8a73e4******bd9****8c20": "Answer" }, "qq_captcha_ticket": "", "qq_captcha_randstr": "", "g-recaptcha-response ": ""}"

3. Handle Second Factor Response After successful first-factor authentication, you'll receive a response containing the following:

  • SecondFactorAuthenticationToken
  • Authentication expiration time
  • Additional authentication options

Example API response


{
"SecondFactorAuthentication": {
"SecondFactorAuthenticationToken": "b1fbbba5-2a5e-41a2-96da-c216df36e6f4",
"ExpireIn": "2021-04-06T08:36:53.3005592Z",
"QRCode": "http://chart.googleapis.com/chart?cht=qr&chs=150x150&chl=otpauth%3A%2F%2Ftotp%2Fanil1%40mail7.io%3Fsecret%3DHBRWENLDHEZGIMBYHFTDINJSMVRDANDBHE4WINJTMYZTCYZSGFRA%26issuer%3Ddev-aniltest",
"ManualEntryCode": "HBRWENLDHEZGIMBYHFTDINJSMVRDANDBHE4WINJTMYZTCYZSGFRA",
"IsGoogleAuthenticatorVerified": false,
"IsAuthenticatorVerified": false,
"IsEmailOtpAuthenticatorVerified": false,
"IsOTPAuthenticatorVerified": false,
"OTPPhoneNo": null,
"OTPStatus": null,
"Email": [
"x**z@e****le.c*m"
],
"EmailOTPStatus": {
"Email": "x**z@e****e.c*m"
},
"IsSecurityQuestionAuthenticatorVerified": false,
"SecurityQuestions": [
{
"QuestionId": "<QuestionId>",
"Question": "<Question>"
}
]
},
"Profile": null,
"access_token": "00000000-0000-0000-0000-000000000000",
"expires_in": "0001-01-01T00:00:00"
}

4. Implement Second Factor Verification Depending on your chosen MFA method:

Example API Call for MFA Validate OTP API :

curl -X PUT \
'https://api.loginradius.com/identity/v2/auth/login/2fa/verification/otp?apikey=&secondfactorauthenticationtoken=&smstemplate2fa=&isvoiceotp=' \
-H 'Cache-Control: no-cache' \
-H 'content-Type: application/json' \
-d "{ "otp": "", "SecurityAnswer": { "db7****8a73e4******bd9****8c20": "Answer" }, "qq_captcha_ticket": "", "qq_captcha_randstr": "", "g-recaptcha-response ": ""}"

The response will be the complete user profile.

Note: APIs requiring API Secret should be called from the backend, while others can be used on the frontend Integration Using Workflows/IO

  • Identity Orchestration (IO): LoginRadius supports low-code/no-code workflows for MFA implementation.
    • Configure workflows in the LoginRadius Admin Console to manage MFA logic without extensive coding.
    • Example: Define rules for triggering MFA based on user roles, IP, or geolocation.
  • Event-Driven Triggers: Use Webhooks or Cloud Connectors to invoke specific actions during MFA workflows.

Note: Some MFA API calls, such as initiating OTP or push notifications, are front-end operations that require execution in the browser. Ensure these APIs are integrated accordingly for optimal functionality.

Front-End Integration

The front-end integration focuses on delivering a branded, user-friendly MFA experience.

Designing MFA Flows

  • Tailor the flow to align with your application’s branding and UX guidelines.
  • Use LoginRadius JavaScript libraries to integrate and manage the user interface for MFA.

Customization Options

LoginRadius provides several options to customize MFA and improve the user experience:

Button Name Change

LRObject.$hooks.call('setButtonsName', {
"emailotp": "Send Email to ",
"otpauthenticator": "Send SMS to Phone",
"securityquestionsauthenticator": "Enter Security Questions",
"googleauthenticator": "Set Google Authenticator app"
});

Label Customization

LRObject.$hooks.call('customizeFormLabel', {
"otp": "Get verification code at %value"
});
  • %value dynamically replaces the phone or email based on user selection.

Change Authenticator Display Order

authenticatorOptionsOrder = ["emailotp", "securityquestion", "googleauth", "sms"];

Step-up Authentication Configuration Guide

Step-Up Authentication enhances security by requiring users to re-authenticate for sensitive actions, even if they are already logged in. This ensures secure identity verification for critical operations.

For instance, when a user tries to change their account password, they must confirm their identity again (e.g., by entering their current password) as an added layer of protection.