Important concepts
Overview
If you are new to Multi-factor authentication, MFA, this page provides a quick summary of how it works and the main terminology used in it.
MFA enhances security by requiring users to authenticate through:
The user enters their primary credentials, typically a username and password (first factor).
Upon successful entry of the primary credentials, the user receives an authentication challenge, prompting them to provide a secondary factor, such as an OTP or biometric verification.
Access to the account or service is only granted when both the primary and secondary factors are successfully verified.
This layered approach reduces the risk of unauthorized access, as an attacker would need to compromise multiple authentication methods to gain access.
Terminology
Authentication challenge
An authentication challenge is a prompt that requires the user to provide additional credentials beyond the primary factor to verify their identity. This typically involves requesting a secondary factor, such as entering an OTP received via SMS/email or approving a push notification from an authenticator app. Authentication challenges are crucial in detecting and preventing unauthorized access by requiring proof of possession or identity beyond a password.
Factors
Factors refer to the different categories of credentials used in MFA:
- Something You Know: Information only the user knows, such as a password or personal identification number (
PIN). - Something You Have: A physical item the user possesses, such as a smartphone or hardware token used for generating one-time passwords (OTPs).
- Something You Are: Biometric characteristics unique to the user, such as fingerprints, facial recognition, or voice patterns.
Each auth challenge has a factor ID in SuperTokens:
These factor IDs get used to configure the MFA requirements for users (except the acccess-denied one).
They are also used to indicate which authentication challenges have completed in the current session.
Factor completion status
You can determine the status of the authentication factors by checking the session's access token payload. In the payload you can find the following claim structure:
{
"st-mfa": {
// c stands for completed, and
// Shows that only the emailpassword factor has been completed
"c": {
// the timestamp when the factor was completed
"emailpassword": 1702877939,
},
// v stands for value
// In this example, the false value indicates that the MFA flow is not completed
// Once the second factor is finalized v will change to true
"v": false
}
}
Each time an authentication factor completes, the SuperTokens backend adds it to the c (completed) object, and then re-evaluates the v boolean based on the MFA requirements for the user.
First factor vs. secondary factor
-
First Factor: The primary authentication method, traditionally a password or
PIN. This is the initial layer of security in the authentication process. -
Secondary Factor: An additional security layer that complements the first factor. Common secondary factors include OTPs sent via email/SMS, authenticator apps like Google Authenticator, or biometric data. Secondary factors enhance security by adding an extra step to the verification process.
A clear distinction exists between first and additional factors in the SDK.
When you call MFA.init on the backend, you need to provide a list of allowed first factors. If using multi-tenancy, you can configure the first factors on a per-tenant basis and leave the init array empty.
The first factors are those allowed to create a new session, whereas any other factor can only modify an existing session.
In case the user calls an additional factor's API without a session, the API responds with a 401 error.
Account linking
Account linking refers to the process of connecting multiple accounts or identities across platforms or services. In the context of MFA, account linking ensures that a user's secondary authentication factors (for example, an authenticator app or backup method) are correctly associated with their primary account. This is crucial for streamlined access and maintaining secure authentication across different services without the need to set up separate MFA methods for each account.
The relation between account linking and MFA
During account linking, the individual login methods create their own "recipe user", and each recipe user links to another recipe user to create one primary user. Theoretically, one can link any recipe user to another (there is no need for them to have the same email or phone number). However, for first factor automatic linking, only link login methods if they have been verified and have the same email.
From an MFA point of view, whenever the user sets up a new passwordless factor (otp-email or otp-sms), this creates a new recipe user for the passwordless recipe. It then auto-links it to the existing session's recipe user. Therefore, it is necessary to enable account linking for MFA to work. In the MFA guide, first factor account linking is not enabled, but you can enable that by following the automatic account linking guide in other parts of the docs.