03. Introduction to Multi-Factor Authentication (MFA)

This codelab introduces Multi-Factor Authentication (MFA) concepts using the cordova-plugin-rdna Cordova plugin. You'll learn how the plugin/SDK's challenge-response system works, understand different authentication flows, and master the terminology needed for implementing secure authentication.

What You'll Learn

Understanding the MFA challenge-response architecture
How Plugin/SDK events map to API responses
Different types of authentication flows and their characteristics
MFA terminology
When and how different challenges are triggered

What You'll Need

Completed RELID Initialization codelab
cordova-plugin-rdna plugin installed and configured
Basic understanding of event-driven programming
Access to the sample app source code for reference

The RELID Plugin/SDK implements Multi-Factor Authentication through a challenge-response mechanism. This system ensures secure, step-by-step verification of user identity through multiple factors.

Core MFA Concepts

Challenge-Response Pattern

The MFA system works on a fundamental challenge-response pattern:

Plugin/SDK Issues Challenge: The Plugin/SDK identifies what information it needs
Event Triggered: Your app receives an event
User Interaction: App collects required information from user
API Response: App responds with appropriate API call
Flow Continuation: Plugin/SDK processes response and continues or completes flow

MFA Flow Initialization

After successful Plugin/SDK initialization, the authentication process begins immediately:

Plugin/SDK Initialization Complete → getUser Challenge → MFA Flow Begins

Challenge Categories

The MFA system uses several categories of challenges:

Category	Purpose	Examples
Identity Verification	Establish user identity	`checkuser(getUser)`
Multi-Factor Verification	Verify user through multiple channels	`otp(getActivationCode)`
Device/Password Authentication	Authenticate using device capabilities/password verification	`pass(getUserConsentForLDA/getPassword)`
Device Management	Handle new device scenarios	`verifyauth(addNewDeviceOptions)`
Session Management	Complete authentication flows	`onUserLoggedIn`

Event-Driven Architecture

The MFA system is completely event-driven:

No polling required: Plugin/SDK pushes events when challenges are needed
Asynchronous processing: Events can be handled at any time
Flow control: Plugin/SDK controls the sequence of challenges

The RELID Plugin/SDK supports three distinct prelogin authentication flows, each designed for specific user scenarios and security requirements.

1. Activation Flow

Purpose: First-time user registration and device setup

When Used:

New users registering for the first time
Users who have never activated on any device
Initial device enrollment

Key Characteristics:

Complete profile setup: Establishes user identity and credentials
Device registration: Registers the current device for future logins

Flow Outcome: User gets registered successfully.

2. Login Flow (Same Device)

Purpose: Authenticate returning users on previously/same registered devices

When Used:

User logs in on a device they've used before
Device is already registered with user's profile
Most common login scenario

Key Characteristics:

Streamlined process: Leverages existing device registration
LDA optimization: Uses Local Device Authentication when available

Flow Outcome: Quick authentication leveraging device trust

3. Login Flow (New Device)

Purpose: Authenticate users on devices they haven't registered before

When Used:

User logs in from a new Device (ex. phone, tablet)
Device is not in user's registered device list
Security verification required for device trust

Key Characteristics:

Enhanced verification: Additional security steps for new device
Verification options: Multiple methods to verify device legitimacy
Device enrollment: Registers new device upon successful authentication

Flow Outcome: User authenticated with new device added to registered devices

Each MFA challenge follows a consistent event → API response pattern. Understanding these mappings is crucial for implementing authentication flows.

Universal Challenge Pattern

Every challenge in the MFA system follows this pattern:

Plugin/SDK Challenge Event → App UI Collection → API Response → Flow Continuation

Core Challenge Mappings

1. User Identification Challenge

Challenge Name	`checkuser`
Event Name	`getUser`
API Name	`setUser`
Purpose	Collect and verify user identifier
When Triggered	Always first challenge after initialization
User Input	Username, email, or user identifier

Flow Pattern:

Plugin/SDK → getUser event → App shows username input → User enters username → setUser API → Next challenge

2. OTP Verification Challenge

Challenge Name	`otp`
Event Name	`getActivationCode`
API Name	`setActivationCode`
Purpose	Verify user through out-of-band authentication
When Triggered	After successful user identification
User Input	OTP code, activation code, or verification code

Flow Pattern:

Plugin/SDK → getActivationCode event → App shows OTP input → User enters code → setActivationCode API → Next challenge

3. Password Authentication Challenge

Challenge Name	`pass`
Event Name	`getPassword`
API Name	`setPassword`
Purpose	Traditional password-based authentication
When Triggered	When LDA is NOT available on device
User Input	User password

Flow Pattern:

Plugin/SDK → getPassword event → App shows password input → User enters password → setPassword API → Authentication complete

4. Local Device Authentication (LDA) Challenge

Challenge Name	`pass`
Event Name	`getUserConsentForLDA`
API Name	`setUserConsentForLDA`
Purpose	Biometric or device-based authentication
When Triggered	When LDA IS available on device
User Input	Consent for biometric authentication

Flow Pattern:

Plugin/SDK → getUserConsentForLDA event → App shows consent dialog → User grants consent → setUserConsentForLDA API → Biometric prompt

5. New Device Verification Challenge

Challenge Name	`verifyauth`
Event Name	`addNewDeviceOptions`
API Name	`performVerifyAuth`
Purpose	Verify legitimacy of new device
When Triggered	During new device login flow
User Input	Selection of verification method

Flow Pattern:

Plugin/SDK → addNewDeviceOptions event → App handles device verification → performVerifyAuth API → Verification process

6. Authentication Completion Event

Challenge Name	N/A (Completion Event)
Event Name	`onUserLoggedIn`
API Name	NA
Purpose	Signal successful authentication completion and user logged in
When Triggered	After all challenges successfully completed
User Input	None (automatic)

Flow Pattern:

Final challenge completed → onUserLoggedIn event → App-to-user session established

Understanding key MFA terminology is essential for implementing and troubleshooting authentication flows.

Authentication Terms

Challenge

A security step that the Plugin/SDK requires the user to complete. Each challenge represents a specific verification requirement.

Example: The checkuser challenge for which Plugin/SDK triggers getUser event requires the user to provide their username.

Event

A callback sent by the Plugin/SDK to your application when a challenge needs to be addressed.

Example: The getActivationCode event indicates the Plugin/SDK needs an OTP from the user.

API Response

The method your application calls to provide the required information for a challenge.

Example: Calling setUser("john.doe") responds to the getUser challenge.

Flow

A complete sequence of challenges from start to successful authentication.

Example: Activation Flow might include: getUser → getActivationCode → getUserConsentForLDA → onUserLoggedIn

Technical Terms

LDA (Local Device Authentication)

Device-based authentication using biometrics (fingerprint, face recognition) or device passcode.

Key Points:

Only available on supported devices
Managed internally by the Plugin/SDK

Multi-Factor Authentication (MFA)

Security method requiring users to provide two or more verification factors.

Flow-Specific Terms

Activation

The initial registration process where a user establishes their identity and enrolls their first device.

Device Registration

The process of adding a device to a user's list of trusted devices.

Device Trust

The security relationship between a user account and a registered device, enabling streamlined future authentication.

Session

The authenticated period between successful login and logout, managed through device tokens.

Error Handling Terms

Long Error Code

Detailed numeric error code providing specific information about what went wrong.

Short Error Code

Generic error category for broad error classification.

Error String

Human-readable error message describing the issue and potential solutions.

Points to consider for API Calls

Critical Timing Rules:

Only call APIs in response to events - Never call MFA APIs without receiving the corresponding challenge event
Sequential processing - Wait for current API to complete before handling next challenge
No duplicate calls - Don't retry API calls unless explicitly handling errors

Correct Flow:

getUser event → setUser API → wait for next event → getActivationCode event → setActivationCode API

Incorrect Flow:

setUser API → getUser event (❌ API called before event)
getUser event → setUser API → setUser API (❌ duplicate API calls)

Congratulations! You've mastered the fundamentals of Multi-Factor Authentication (MFA) with the RELID Plugin/SDK:

✅ Challenge-Response Architecture: Understanding how Plugin/SDK events map to API responses ✅ Flow Types: Activation, Same Device Login, and New Device Login characteristics ✅ Event Integration: Extending event managers for MFA challenge handling ✅ API Patterns: Proper response patterns and error handling ✅ MFA Terminology: Essential security and technical concepts ✅ Best Practices: Timing, error handling, and implementation guidelines

Key Concepts Mastered

Challenge System: How the Plugin/SDK uses events to request information and APIs to receive responses
Flow Differentiation: When and why different authentication flows are used
Event-Driven Architecture: Building responsive authentication experiences

MFA Foundation Knowledge

You now understand:

Why MFA matters: Multiple verification factors provide enhanced security
How challenges work: Event-driven requests for specific authentication information
When flows differ: Device registration state determines authentication requirements
What responses mean: API success/error patterns and proper error handling

Next Steps

With this foundation, you're ready for:

Activation Flow Codelab: Implementing complete first-time user registration
Login Flow Codelab: Building returning user authentication experiences

What You'll Learn

What You'll Need

Core MFA Concepts

Challenge-Response Pattern

MFA Flow Initialization

Challenge Categories

Event-Driven Architecture

1. Activation Flow

2. Login Flow (Same Device)

3. Login Flow (New Device)

Universal Challenge Pattern

Core Challenge Mappings

1. User Identification Challenge

2. OTP Verification Challenge

3. Password Authentication Challenge

4. Local Device Authentication (LDA) Challenge

5. New Device Verification Challenge

6. Authentication Completion Event

Authentication Terms

Challenge

Event

API Response

Flow

Technical Terms

LDA (Local Device Authentication)

Multi-Factor Authentication (MFA)

Flow-Specific Terms

Activation

Device Registration

Device Trust

Session

Error Handling Terms

Long Error Code

Short Error Code

Error String

Points to consider for API Calls

Key Concepts Mastered

MFA Foundation Knowledge

Next Steps

References