diff --git a/.version b/.version
index 268fccb1..fbbf144b 100644
--- a/.version
+++ b/.version
@@ -1 +1 @@
-v5.5.0
+v5.5.1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63c7a65e..2b6b8529 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
# Change Log
+## [v5.5.1](https://github.com/auth0/react-native-auth0/tree/v5.5.1) (2026-04-23)
+
+[Full Changelog](https://github.com/auth0/react-native-auth0/compare/v5.5.0...v5.5.1)
+
+**Fixed**
+
+- fix: remove conflicting broad scheme from MainActivity to prevent Android disambiguation dialog [\#1514](https://github.com/auth0/react-native-auth0/pull/1514) ([subhankarmaiti](https://github.com/subhankarmaiti))
+- fix: filter universal link callbacks by Auth0 domain in iOS [\#1512](https://github.com/auth0/react-native-auth0/pull/1512) ([subhankarmaiti](https://github.com/subhankarmaiti))
+
## [v5.5.0](https://github.com/auth0/react-native-auth0/tree/v5.5.0) (2026-04-09)
[Full Changelog](https://github.com/auth0/react-native-auth0/compare/v5.4.1...v5.5.0)
diff --git a/EXAMPLES-WEB.md b/EXAMPLES-WEB.md
index 24f7b7ed..21ce8869 100644
--- a/EXAMPLES-WEB.md
+++ b/EXAMPLES-WEB.md
@@ -158,14 +158,120 @@ const App = () => {
};
```
-## Unsupported Web Features
+## 3. MFA Flexible Factors Grant (Web)
-For security reasons, the web platform **does not support** direct authentication grants. The following methods from the `auth` provider will throw a `NotImplemented` error:
+The MFA Flexible Factors Grant is fully supported on the web platform. It uses the `@auth0/auth0-spa-js` MFA API under the hood.
-- `auth.passwordRealm()`
-- `auth.loginWithOTP()`
-- `auth.loginWithSMS()`
-- `auth.loginWithEmail()`
-- `auth.refreshToken()`
+### Using MFA with Hooks
-All these flows should be configured in your [Auth0 Universal Login](https://auth0.com/docs/universal-login) page and initiated via the `authorize()` method.
+```tsx
+import React, { useState } from 'react';
+import { View, Button, TextInput, Text } from 'react-native';
+import { useAuth0, MfaError, MfaErrorCodes } from 'react-native-auth0';
+
+function MfaScreen({ mfaToken }: { mfaToken: string }) {
+ const { mfa } = useAuth0();
+ const [otp, setOtp] = useState('');
+
+ const listAuthenticators = async () => {
+ try {
+ const authenticators = await mfa.getAuthenticators({ mfaToken });
+ console.log('Authenticators:', authenticators);
+ } catch (error) {
+ if (error instanceof MfaError) {
+ console.error('MFA error:', error.type, error.message);
+ }
+ }
+ };
+
+ const enrollTotp = async () => {
+ try {
+ const challenge = await mfa.enroll({ mfaToken, type: 'otp' });
+ if (challenge.type === 'totp') {
+ console.log('Scan QR:', challenge.barcodeUri);
+ console.log('Secret:', challenge.secret);
+ }
+ } catch (error) {
+ if (error instanceof MfaError) {
+ console.error('Enrollment error:', error.type);
+ }
+ }
+ };
+
+ const verifyOtp = async () => {
+ try {
+ const credentials = await mfa.verify({ mfaToken, otp });
+ console.log('Authenticated!', credentials.accessToken);
+ } catch (error) {
+ if (error instanceof MfaError) {
+ switch (error.type) {
+ case MfaErrorCodes.INVALID_OTP:
+ console.log('Incorrect code');
+ break;
+ case MfaErrorCodes.TOO_MANY_ATTEMPTS:
+ console.log('Too many attempts');
+ break;
+ case MfaErrorCodes.EXPIRED_MFA_TOKEN:
+ console.log('Session expired');
+ break;
+ }
+ }
+ }
+ };
+
+ return (
+
+
+
+
+
+
+ );
+}
+```
+
+### Using MFA with Auth0 Class
+
+```typescript
+import Auth0, { MfaError, MfaErrorCodes } from 'react-native-auth0';
+
+const auth0 = new Auth0({
+ domain: 'YOUR_AUTH0_DOMAIN',
+ clientId: 'YOUR_AUTH0_CLIENT_ID',
+});
+
+// List authenticators
+const authenticators = await auth0.mfa.getAuthenticators({
+ mfaToken: 'mfa_token',
+});
+
+// Enroll TOTP
+const challenge = await auth0.mfa.enroll({
+ mfaToken: 'mfa_token',
+ type: 'otp',
+});
+
+// Enroll SMS
+const smsChallenge = await auth0.mfa.enroll({
+ mfaToken: 'mfa_token',
+ phoneNumber: '+12025550135',
+});
+
+// Challenge an authenticator
+const challengeResult = await auth0.mfa.challenge({
+ mfaToken: 'mfa_token',
+ authenticatorId: 'sms|dev_123',
+});
+
+// Verify OTP
+const credentials = await auth0.mfa.verify({
+ mfaToken: 'mfa_token',
+ otp: '123456',
+});
+```
+
+## Web Platform Notes
+
+The web platform supports direct authentication grants including `auth.passwordRealm()`, `auth.createUser()`, `auth.resetPassword()`, and the MFA Flexible Factors Grant. These methods make direct HTTP calls to the Auth0 API.
+
+Token refresh is handled automatically by `credentialsManager.getCredentials()` on the web. The `auth.refreshToken()` method is not available.
diff --git a/EXAMPLES.md b/EXAMPLES.md
index deb3ee99..1b6acc98 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -58,6 +58,10 @@
- [Using SSO Exchange with Hooks](#using-sso-exchange-with-hooks)
- [Using SSO Exchange with Auth0 Class](#using-sso-exchange-with-auth0-class)
- [Sending the Session Transfer Token](#sending-the-session-transfer-token)
+- [MFA Flexible Factors Grant](#mfa-flexible-factors-grant)
+ - [Using MFA with Hooks](#using-mfa-with-hooks)
+ - [Using MFA with Auth0 Class](#using-mfa-with-auth0-class)
+ - [MFA Error Handling](#mfa-error-handling)
- [Bot Protection](#bot-protection)
- [Domain Switching](#domain-switching)
- [Android](#android)
@@ -1243,6 +1247,275 @@ function WebAppView() {
> **Note**: Cookie injection is platform-specific and may require additional configuration. The query parameter method is generally more straightforward and recommended for most use cases.
+## MFA Flexible Factors Grant
+
+The MFA Flexible Factors Grant provides programmatic control over Multi-Factor Authentication flows. Instead of relying solely on Universal Login, you can build custom MFA experiences — listing enrolled authenticators, enrolling new factors, triggering challenges, and verifying codes — all from your own UI.
+
+This feature works across all platforms (iOS, Android, and Web).
+
+### Using MFA with Hooks
+
+```tsx
+import React, { useState } from 'react';
+import { View, Button, TextInput, Text, Alert } from 'react-native';
+import { useAuth0, MfaError, MfaErrorCodes } from 'react-native-auth0';
+
+function MfaScreen({ mfaToken }: { mfaToken: string }) {
+ const { mfa } = useAuth0();
+ const [otp, setOtp] = useState('');
+
+ // List enrolled authenticators
+ const listAuthenticators = async () => {
+ try {
+ const authenticators = await mfa.getAuthenticators({ mfaToken });
+ console.log('Enrolled authenticators:', authenticators);
+ } catch (error) {
+ if (error instanceof MfaError) {
+ console.error('MFA error:', error.type, error.message);
+ }
+ }
+ };
+
+ // Enroll a new TOTP authenticator
+ const enrollTotp = async () => {
+ try {
+ const challenge = await mfa.enroll({ mfaToken, type: 'otp' });
+ if (challenge.type === 'totp') {
+ console.log('Scan this barcode:', challenge.barcodeUri);
+ console.log('Or enter this secret:', challenge.secret);
+ }
+ } catch (error) {
+ if (error instanceof MfaError) {
+ switch (error.type) {
+ case MfaErrorCodes.ENROLLMENT_FAILED:
+ Alert.alert('Error', 'Enrollment failed. Please try again.');
+ break;
+ case MfaErrorCodes.EXPIRED_MFA_TOKEN:
+ Alert.alert('Error', 'MFA session expired. Please start over.');
+ break;
+ }
+ }
+ }
+ };
+
+ // Enroll an SMS factor
+ const enrollSms = async () => {
+ try {
+ const challenge = await mfa.enroll({
+ mfaToken,
+ phoneNumber: '+12025550135',
+ });
+ console.log('OOB code:', challenge.oobCode);
+ } catch (error) {
+ if (
+ error instanceof MfaError &&
+ error.type === MfaErrorCodes.INVALID_PHONE_NUMBER
+ ) {
+ Alert.alert('Error', 'Invalid phone number.');
+ }
+ }
+ };
+
+ // Trigger a challenge for an existing authenticator
+ const triggerChallenge = async (authenticatorId: string) => {
+ try {
+ const result = await mfa.challenge({ mfaToken, authenticatorId });
+ console.log('Challenge type:', result.challengeType);
+ console.log('OOB code:', result.oobCode);
+ } catch (error) {
+ if (error instanceof MfaError) {
+ console.error('Challenge failed:', error.type);
+ }
+ }
+ };
+
+ // Verify an OTP code - this completes authentication
+ const verifyOtp = async () => {
+ try {
+ const credentials = await mfa.verify({ mfaToken, otp });
+ console.log('Authentication complete!', credentials.accessToken);
+ // User is now logged in - state is automatically updated
+ } catch (error) {
+ if (error instanceof MfaError) {
+ switch (error.type) {
+ case MfaErrorCodes.INVALID_OTP:
+ Alert.alert('Error', 'Incorrect code. Please try again.');
+ break;
+ case MfaErrorCodes.TOO_MANY_ATTEMPTS:
+ Alert.alert('Error', 'Too many attempts. Please wait.');
+ break;
+ case MfaErrorCodes.EXPIRED_MFA_TOKEN:
+ Alert.alert('Error', 'Session expired. Please start over.');
+ break;
+ }
+ }
+ }
+ };
+
+ return (
+
+
+
+
+
+
+
+ );
+}
+```
+
+### Using MFA with Auth0 Class
+
+```typescript
+import Auth0, { MfaError, MfaErrorCodes } from 'react-native-auth0';
+
+const auth0 = new Auth0({
+ domain: 'YOUR_AUTH0_DOMAIN',
+ clientId: 'YOUR_AUTH0_CLIENT_ID',
+});
+
+// List enrolled authenticators
+const authenticators = await auth0.mfa.getAuthenticators({
+ mfaToken: 'mfa_token_from_login',
+ factorsAllowed: ['otp', 'oob'], // Optional: filter by factor type
+});
+
+// Enroll a TOTP authenticator
+const totpChallenge = await auth0.mfa.enroll({
+ mfaToken: 'mfa_token',
+ type: 'otp',
+});
+// totpChallenge.type === 'totp'
+// totpChallenge.barcodeUri - QR code URI
+// totpChallenge.secret - Manual entry secret
+
+// Enroll via SMS
+const smsChallenge = await auth0.mfa.enroll({
+ mfaToken: 'mfa_token',
+ phoneNumber: '+12025550135',
+});
+
+// Enroll via email
+const emailChallenge = await auth0.mfa.enroll({
+ mfaToken: 'mfa_token',
+ email: 'user@example.com',
+});
+
+// Enroll via voice call
+const voiceChallenge = await auth0.mfa.enroll({
+ mfaToken: 'mfa_token',
+ phoneNumber: '+12025550135',
+ voice: true,
+});
+
+// Trigger an OOB challenge
+const challenge = await auth0.mfa.challenge({
+ mfaToken: 'mfa_token',
+ authenticatorId: 'sms|dev_123',
+});
+
+// Verify with OTP
+const credentials = await auth0.mfa.verify({
+ mfaToken: 'mfa_token',
+ otp: '123456',
+});
+
+// Verify with OOB code
+const credentialsOob = await auth0.mfa.verify({
+ mfaToken: 'mfa_token',
+ oobCode: 'oob_code_from_challenge',
+ bindingCode: '654321', // Optional, for SMS/email OOB
+});
+
+// Verify with recovery code
+const credentialsRecovery = await auth0.mfa.verify({
+ mfaToken: 'mfa_token',
+ recoveryCode: 'ABCDEF123456',
+});
+```
+
+### MFA Error Handling
+
+All MFA operations throw `MfaError` with a normalized, platform-agnostic `type` property:
+
+```typescript
+import { MfaError, MfaErrorCodes } from 'react-native-auth0';
+
+try {
+ await auth0.mfa.verify({ mfaToken, otp: '123456' });
+} catch (error) {
+ if (error instanceof MfaError) {
+ switch (error.type) {
+ case MfaErrorCodes.INVALID_OTP:
+ // OTP code is incorrect
+ break;
+ case MfaErrorCodes.INVALID_OOB_CODE:
+ // OOB code is incorrect
+ break;
+ case MfaErrorCodes.INVALID_RECOVERY_CODE:
+ // Recovery code is incorrect
+ break;
+ case MfaErrorCodes.EXPIRED_MFA_TOKEN:
+ // MFA token has expired - restart the MFA flow
+ break;
+ case MfaErrorCodes.INVALID_MFA_TOKEN:
+ // MFA token is invalid
+ break;
+ case MfaErrorCodes.TOO_MANY_ATTEMPTS:
+ // Rate limited - wait before retrying
+ break;
+ case MfaErrorCodes.ENROLLMENT_FAILED:
+ // Enrollment operation failed
+ break;
+ case MfaErrorCodes.INVALID_PHONE_NUMBER:
+ // Phone number is invalid for enrollment
+ break;
+ case MfaErrorCodes.INVALID_EMAIL:
+ // Email is invalid for enrollment
+ break;
+ case MfaErrorCodes.CHALLENGE_FAILED:
+ // Challenge request failed
+ break;
+ case MfaErrorCodes.AUTHENTICATOR_NOT_FOUND:
+ // Authenticator not found or not enrolled
+ break;
+ case MfaErrorCodes.UNSUPPORTED_FACTOR:
+ // MFA factor type is not supported
+ break;
+ case MfaErrorCodes.ASSOCIATION_REQUIRED:
+ // User must enroll before using the authenticator
+ break;
+ default:
+ console.error('MFA error:', error.message);
+ }
+ }
+}
+```
+
+| Error Code | Description | Auth0 API Code | Native Bridge Code |
+| ------------------------- | ----------------------------------------------- | ------------------------------ | ---------------------- |
+| `INVALID_OTP` | OTP code is incorrect | `invalid_otp`, `invalid_grant` | |
+| `INVALID_OOB_CODE` | OOB code is incorrect | `invalid_oob_code` | |
+| `INVALID_BINDING_CODE` | Binding code is incorrect | `invalid_binding_code` | |
+| `INVALID_RECOVERY_CODE` | Recovery code is incorrect | `invalid_recovery_code` | |
+| `ENROLLMENT_FAILED` | MFA enrollment failed | `mfa_enrollment_failed` | `MFA_ENROLLMENT_ERROR` |
+| `INVALID_PHONE_NUMBER` | Phone number is invalid for enrollment | `invalid_phone_number` | |
+| `INVALID_EMAIL` | Email is invalid for enrollment | `invalid_email` | |
+| `EXPIRED_MFA_TOKEN` | MFA token has expired | `expired_token` | |
+| `INVALID_MFA_TOKEN` | MFA token is invalid | `mfa_token_invalid` | |
+| `TOO_MANY_ATTEMPTS` | Rate limited - too many verification attempts | `too_many_attempts` | |
+| `CHALLENGE_FAILED` | MFA challenge request failed | `mfa_challenge_failed` | `MFA_CHALLENGE_ERROR` |
+| `AUTHENTICATOR_NOT_FOUND` | Authenticator not found or not enrolled | | |
+| `UNSUPPORTED_FACTOR` | MFA factor type is not supported | `unsupported_challenge_type` | |
+| `ASSOCIATION_REQUIRED` | User must enroll before using the authenticator | `association_required` | |
+| `MFA_ERROR` | Generic MFA error | | `MFA_VERIFY_ERROR` |
+| `UNKNOWN_MFA_ERROR` | Unknown or uncategorized MFA error | | |
+
## Bot Protection
If you are using the [Bot Protection](https://auth0.com/docs/anomaly-detection/bot-protection) feature and performing database login/signup via the Authentication API, you need to handle the `requires_verification` error. It indicates that the request was flagged as suspicious and an additional verification step is necessary to log the user in. That verification step is web-based, so you need to use Universal Login to complete it.
diff --git a/README.md b/README.md
index a4aa5ca0..0f6ecdad 100644
--- a/README.md
+++ b/README.md
@@ -303,6 +303,39 @@ https://{YOUR_AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback
> Replace `{PRODUCT_BUNDLE_IDENTIFIER}` and `{YOUR_AUTH0_DOMAIN}` with your actual product bundle identifier and Auth0 domain. Ensure that {PRODUCT_BUNDLE_IDENTIFIER} is all lowercase.
+#### Expo
+
+When using Expo, the callback URL format depends on whether you provide a `customScheme` in your `app.json` plugin configuration.
+
+##### With `customScheme`
+
+If you set a `customScheme` (e.g., `"auth0sample"`) in your `app.json`:
+
+```text
+{YOUR_CUSTOM_SCHEME}://{YOUR_AUTH0_DOMAIN}/ios/{BUNDLE_IDENTIFIER}/callback,
+{YOUR_CUSTOM_SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{PACKAGE_NAME}/callback
+```
+
+**Example:** If your custom scheme is `auth0sample`, your Auth0 domain is `example.us.auth0.com`, your iOS bundle identifier is `com.example.myapp`, and your Android package name is `com.example.myapp`:
+
+```text
+auth0sample://example.us.auth0.com/ios/com.example.myapp/callback,
+auth0sample://example.us.auth0.com/android/com.example.myapp/callback
+```
+
+> **Note:** The URL scheme uses `customScheme`, but the path always contains the bundle identifier (iOS) or package name (Android), **not** the custom scheme.
+
+##### Without `customScheme`
+
+If you do not provide a `customScheme`, the SDK defaults to `{BUNDLE_IDENTIFIER}.auth0` / `{PACKAGE_NAME}.auth0`:
+
+```text
+{BUNDLE_IDENTIFIER}.auth0://{YOUR_AUTH0_DOMAIN}/ios/{BUNDLE_IDENTIFIER}/callback,
+{PACKAGE_NAME}.auth0://{YOUR_AUTH0_DOMAIN}/android/{PACKAGE_NAME}/callback
+```
+
+> All values must be **lowercase** with **no trailing slash**.
+
#### Configure an associated domain for iOS
> [!IMPORTANT]
@@ -712,6 +745,57 @@ try {
| `NO_NETWORK` | `NO_NETWORK` | | |
| `API_ERROR` | `API_ERROR` | | |
+### MFA errors
+
+All MFA operations (via `auth0.mfa` or the `mfa` property from `useAuth0()`) throw `MfaError` with a normalized `type` property:
+
+```js
+import { MfaError, MfaErrorCodes } from 'react-native-auth0';
+
+try {
+ const credentials = await auth0.mfa.verify({ mfaToken, otp: '123456' });
+} catch (error) {
+ if (error instanceof MfaError) {
+ switch (error.type) {
+ case MfaErrorCodes.INVALID_OTP:
+ console.log('Incorrect OTP code.');
+ break;
+ case MfaErrorCodes.EXPIRED_MFA_TOKEN:
+ console.log('MFA session expired. Please start over.');
+ break;
+ case MfaErrorCodes.TOO_MANY_ATTEMPTS:
+ console.log('Too many attempts. Please wait.');
+ break;
+ case MfaErrorCodes.ENROLLMENT_FAILED:
+ console.log('MFA enrollment failed.');
+ break;
+ default:
+ console.error('MFA error:', error.message);
+ }
+ }
+}
+```
+
+| Generic Error Code | Description | Auth0 API Code |
+| ------------------------- | -------------------------------------- | ------------------------------ |
+| `INVALID_OTP` | OTP code is incorrect | `invalid_otp`, `invalid_grant` |
+| `INVALID_OOB_CODE` | OOB code is incorrect | `invalid_oob_code` |
+| `INVALID_BINDING_CODE` | Binding code is incorrect | `invalid_binding_code` |
+| `INVALID_RECOVERY_CODE` | Recovery code is incorrect | `invalid_recovery_code` |
+| `ENROLLMENT_FAILED` | MFA enrollment failed | `mfa_enrollment_failed` |
+| `INVALID_PHONE_NUMBER` | Phone number is invalid for enrollment | `invalid_phone_number` |
+| `INVALID_EMAIL` | Email is invalid for enrollment | `invalid_email` |
+| `EXPIRED_MFA_TOKEN` | MFA token has expired | `expired_token` |
+| `INVALID_MFA_TOKEN` | MFA token is invalid | `mfa_token_invalid` |
+| `TOO_MANY_ATTEMPTS` | Rate limited | `too_many_attempts` |
+| `CHALLENGE_FAILED` | MFA challenge failed | `mfa_challenge_failed` |
+| `AUTHENTICATOR_NOT_FOUND` | Authenticator not found | |
+| `UNSUPPORTED_FACTOR` | Factor type not supported | `unsupported_challenge_type` |
+| `ASSOCIATION_REQUIRED` | User must enroll first | `association_required` |
+| `UNKNOWN_MFA_ERROR` | Unknown MFA error | |
+
+For detailed MFA usage examples, see [EXAMPLES.md](EXAMPLES.md#mfa-flexible-factors-grant) and [EXAMPLES-WEB.md](EXAMPLES-WEB.md#3-mfa-flexible-factors-grant-web).
+
### WebAuth errors
**Before (Platform-Specific Codes)**
@@ -826,6 +910,11 @@ This library provides a unified API across Native (iOS/Android) and Web platform
| `auth.createUser()` | ✅ | ✅ | Calls the `/dbconnections/signup` endpoint. Works on both platforms. |
| `auth.resetPassword()` | ✅ | ✅ | Calls the `/dbconnections/change_password` endpoint. Works on both platforms. |
| `users(token).patchUser()` | ✅ | ✅ | Calls the Management API. Works on any platform with a valid token, but use with caution in the browser. |
+| **MFA Flexible Factors Grant** | | | --- |
+| `mfa.getAuthenticators()` | ✅ | ✅ | Lists enrolled MFA authenticators for the user. |
+| `mfa.enroll()` | ✅ | ✅ | Enrolls a new MFA factor (OTP, SMS, email, voice, push). |
+| `mfa.challenge()` | ✅ | ✅ | Triggers an MFA challenge for an enrolled authenticator. |
+| `mfa.verify()` | ✅ | ✅ | Verifies an MFA code (OTP, OOB, recovery) and returns credentials. |
## Troubleshooting
diff --git a/android/src/main/java/com/auth0/react/A0Auth0Module.kt b/android/src/main/java/com/auth0/react/A0Auth0Module.kt
index ade908c0..4e4de9e3 100644
--- a/android/src/main/java/com/auth0/react/A0Auth0Module.kt
+++ b/android/src/main/java/com/auth0/react/A0Auth0Module.kt
@@ -16,11 +16,14 @@ import com.auth0.android.dpop.DPoPException
import com.auth0.android.provider.WebAuthProvider
import com.auth0.android.result.Credentials
import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Arguments
import com.facebook.react.bridge.Promise
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableArray
import com.facebook.react.bridge.ReadableMap
import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.bridge.WritableNativeArray
import com.facebook.react.bridge.WritableNativeMap
import java.net.MalformedURLException
import java.net.URL
@@ -88,6 +91,7 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
private var useDPoP: Boolean = true
private var auth0: Auth0? = null
+ private var mfaClient: MfaClient? = null
private lateinit var secureCredentialsManager: SecureCredentialsManager
private var webAuthPromise: Promise? = null
@@ -177,6 +181,7 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
this.useDPoP = useDPoP ?: true
auth0 = Auth0.getInstance(clientId, domain)
+ mfaClient = MfaClient(auth0!!, this.useDPoP, reactContext)
val authAPI = AuthenticationAPIClient(auth0!!)
if (this.useDPoP) {
@@ -507,6 +512,30 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
})
}
+ @ReactMethod
+ override fun getMfaAuthenticators(mfaToken: String, factorsAllowed: ReadableArray?, promise: Promise) {
+ mfaClient?.getAuthenticators(mfaToken, factorsAllowed, promise)
+ ?: promise.reject("NOT_INITIALIZED", "Auth0 not initialized")
+ }
+
+ @ReactMethod
+ override fun mfaEnroll(mfaToken: String, type: String, value: String?, promise: Promise) {
+ mfaClient?.enroll(mfaToken, type, value, promise)
+ ?: promise.reject("NOT_INITIALIZED", "Auth0 not initialized")
+ }
+
+ @ReactMethod
+ override fun mfaChallenge(mfaToken: String, authenticatorId: String, promise: Promise) {
+ mfaClient?.challenge(mfaToken, authenticatorId, promise)
+ ?: promise.reject("NOT_INITIALIZED", "Auth0 not initialized")
+ }
+
+ @ReactMethod
+ override fun mfaVerify(mfaToken: String, type: String, code: String, bindingCode: String?, promise: Promise) {
+ mfaClient?.verify(mfaToken, type, code, bindingCode, promise)
+ ?: promise.reject("NOT_INITIALIZED", "Auth0 not initialized")
+ }
+
override fun onActivityResult(activity: Activity, requestCode: Int, resultCode: Int, data: Intent?) {
// No-op
}
diff --git a/android/src/main/java/com/auth0/react/MfaClient.kt b/android/src/main/java/com/auth0/react/MfaClient.kt
new file mode 100644
index 00000000..465964f9
--- /dev/null
+++ b/android/src/main/java/com/auth0/react/MfaClient.kt
@@ -0,0 +1,209 @@
+package com.auth0.react
+
+import com.auth0.android.Auth0
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.mfa.MfaEnrollmentType
+import com.auth0.android.authentication.mfa.MfaException
+import com.auth0.android.authentication.mfa.MfaVerificationType
+import com.auth0.android.result.Authenticator
+import com.auth0.android.result.Credentials
+import com.auth0.android.result.EnrollmentChallenge
+import com.auth0.android.result.OobEnrollmentChallenge
+import com.auth0.android.result.RecoveryCodeEnrollmentChallenge
+import com.auth0.android.result.TotpEnrollmentChallenge
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.WritableNativeArray
+import com.facebook.react.bridge.WritableNativeMap
+
+enum class MfaFactorType(val value: String) {
+ PHONE("phone"),
+ EMAIL("email"),
+ OTP("otp"),
+ PUSH("push"),
+ VOICE("voice");
+
+ companion object {
+ fun fromString(type: String): MfaFactorType? =
+ entries.find { it.value == type }
+ }
+}
+
+enum class MfaVerifyType(val value: String) {
+ OTP("otp"),
+ OOB("oob"),
+ RECOVERY_CODE("recoveryCode");
+
+ companion object {
+ fun fromString(type: String): MfaVerifyType? =
+ entries.find { it.value == type }
+ }
+}
+
+class MfaClient(
+ private val auth0: Auth0,
+ private val useDPoP: Boolean,
+ private val reactContext: ReactApplicationContext
+) {
+
+ private val client: AuthenticationAPIClient by lazy {
+ AuthenticationAPIClient(auth0).apply {
+ if (useDPoP) {
+ useDPoP(reactContext)
+ }
+ }
+ }
+
+ fun getAuthenticators(mfaToken: String, factorsAllowed: ReadableArray?, promise: Promise) {
+ val mfaClient = client.mfaClient(mfaToken)
+
+ val factors = mutableListOf()
+ factorsAllowed?.let {
+ for (i in 0 until it.size()) {
+ it.getString(i)?.let { factor -> factors.add(factor) }
+ }
+ }
+
+ mfaClient.getAuthenticators(factors).start(
+ object : com.auth0.android.callback.Callback, MfaException.MfaListAuthenticatorsException> {
+ override fun onSuccess(result: List) {
+ val array = WritableNativeArray()
+ for (authenticator in result) {
+ val map = WritableNativeMap().apply {
+ putString("id", authenticator.id)
+ putString("authenticatorType", authenticator.authenticatorType)
+ putBoolean("active", authenticator.active)
+ authenticator.name?.let { putString("name", it) }
+ authenticator.oobChannel?.let { putString("oobChannel", it) }
+ }
+ array.pushMap(map)
+ }
+ promise.resolve(array)
+ }
+
+ override fun onFailure(error: MfaException.MfaListAuthenticatorsException) {
+ promise.reject(error.getCode(), error.getDescription(), error)
+ }
+ }
+ )
+ }
+
+ fun enroll(mfaToken: String, type: String, value: String?, promise: Promise) {
+ val mfaClient = client.mfaClient(mfaToken)
+
+ val factorType = MfaFactorType.fromString(type)
+ if (factorType == null) {
+ promise.reject("MFA_ENROLLMENT_ERROR", "Unsupported enrollment type: $type")
+ return
+ }
+
+ val enrollmentType = when (factorType) {
+ MfaFactorType.PHONE -> {
+ if (value == null) {
+ promise.reject("MFA_ENROLLMENT_ERROR", "Phone number is required for phone enrollment")
+ return
+ }
+ MfaEnrollmentType.Phone(value)
+ }
+ MfaFactorType.EMAIL -> {
+ if (value == null) {
+ promise.reject("MFA_ENROLLMENT_ERROR", "Email is required for email enrollment")
+ return
+ }
+ MfaEnrollmentType.Email(value)
+ }
+ MfaFactorType.OTP -> MfaEnrollmentType.Otp
+ MfaFactorType.PUSH -> MfaEnrollmentType.Push
+ MfaFactorType.VOICE -> {
+ if (value == null) {
+ promise.reject("MFA_ENROLLMENT_ERROR", "Phone number is required for voice enrollment")
+ return
+ }
+ MfaEnrollmentType.Phone(value)
+ }
+ }
+
+ mfaClient.enroll(enrollmentType).start(
+ object : com.auth0.android.callback.Callback {
+ override fun onSuccess(result: EnrollmentChallenge) {
+ val map = WritableNativeMap()
+ when (result) {
+ is TotpEnrollmentChallenge -> {
+ map.putString("type", "totp")
+ map.putString("barcodeUri", result.barcodeUri)
+ map.putString("secret", result.manualInputCode)
+ }
+ is OobEnrollmentChallenge -> {
+ map.putString("type", "oob")
+ map.putString("oobCode", result.oobCode)
+ result.bindingMethod?.let { map.putString("bindingMethod", it) }
+ }
+ is RecoveryCodeEnrollmentChallenge -> {
+ map.putString("type", "recovery-code")
+ map.putString("recoveryCode", result.recoveryCode)
+ }
+ else -> {
+ map.putString("type", "unknown")
+ }
+ }
+ promise.resolve(map)
+ }
+
+ override fun onFailure(error: MfaException.MfaEnrollmentException) {
+ promise.reject(error.getCode(), error.getDescription(), error)
+ }
+ }
+ )
+ }
+
+ fun challenge(mfaToken: String, authenticatorId: String, promise: Promise) {
+ val mfaClient = client.mfaClient(mfaToken)
+
+ mfaClient.challenge(authenticatorId).start(
+ object : com.auth0.android.callback.Callback {
+ override fun onSuccess(result: com.auth0.android.result.Challenge) {
+ val map = WritableNativeMap().apply {
+ putString("challengeType", result.challengeType)
+ result.oobCode?.let { putString("oobCode", it) }
+ result.bindingMethod?.let { putString("bindingMethod", it) }
+ }
+ promise.resolve(map)
+ }
+
+ override fun onFailure(error: MfaException.MfaChallengeException) {
+ promise.reject(error.getCode(), error.getDescription(), error)
+ }
+ }
+ )
+ }
+
+ fun verify(mfaToken: String, type: String, code: String, bindingCode: String?, promise: Promise) {
+ val verifyType = MfaVerifyType.fromString(type)
+ if (verifyType == null) {
+ promise.reject("MFA_VERIFY_ERROR", "Unsupported verification type: $type")
+ return
+ }
+
+ val mfaClient = client.mfaClient(mfaToken)
+
+ val verificationType = when (verifyType) {
+ MfaVerifyType.OTP -> MfaVerificationType.Otp(code)
+ MfaVerifyType.OOB -> MfaVerificationType.Oob(oobCode = code, bindingCode = bindingCode)
+ MfaVerifyType.RECOVERY_CODE -> MfaVerificationType.RecoveryCode(code)
+ }
+
+ mfaClient.verify(verificationType).start(
+ object : com.auth0.android.callback.Callback {
+ override fun onSuccess(result: Credentials) {
+ val map = CredentialsParser.toMap(result)
+ promise.resolve(map)
+ }
+
+ override fun onFailure(error: MfaException.MfaVerifyException) {
+ promise.reject(error.getCode(), error.getDescription(), error)
+ }
+ }
+ )
+ }
+}
diff --git a/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt b/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
index f0c26d10..7e0d1699 100644
--- a/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
+++ b/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
@@ -120,4 +120,39 @@ abstract class A0Auth0Spec(context: ReactApplicationContext) : ReactContextBaseJ
organization: String?,
promise: Promise
)
+
+ @ReactMethod
+ @DoNotStrip
+ abstract fun getMfaAuthenticators(
+ mfaToken: String,
+ factorsAllowed: com.facebook.react.bridge.ReadableArray?,
+ promise: Promise
+ )
+
+ @ReactMethod
+ @DoNotStrip
+ abstract fun mfaEnroll(
+ mfaToken: String,
+ type: String,
+ value: String?,
+ promise: Promise
+ )
+
+ @ReactMethod
+ @DoNotStrip
+ abstract fun mfaChallenge(
+ mfaToken: String,
+ authenticatorId: String,
+ promise: Promise
+ )
+
+ @ReactMethod
+ @DoNotStrip
+ abstract fun mfaVerify(
+ mfaToken: String,
+ type: String,
+ code: String,
+ bindingCode: String?,
+ promise: Promise
+ )
}
\ No newline at end of file
diff --git a/example/src/App.web.tsx b/example/src/App.web.tsx
index 13830002..e4dcec20 100644
--- a/example/src/App.web.tsx
+++ b/example/src/App.web.tsx
@@ -6,8 +6,23 @@ import {
Text,
StyleSheet,
ActivityIndicator,
+ TouchableOpacity,
+ Image,
+ Linking,
} from 'react-native';
-import Auth0, { Auth0Provider, useAuth0, User } from 'react-native-auth0';
+import Auth0, {
+ Auth0Provider,
+ useAuth0,
+ User,
+ MfaError,
+ MfaErrorCodes,
+ MfaFactorType,
+} from 'react-native-auth0';
+import type {
+ MfaAuthenticator,
+ MfaEnrollmentChallenge,
+ MfaChallengeResult,
+} from 'react-native-auth0';
import config from './auth0-configuration';
import Button from './components/Button';
@@ -15,6 +30,16 @@ import Header from './components/Header';
import Result from './components/Result';
import LabeledInput from './components/LabeledInput';
+type MfaStep =
+ | 'idle'
+ | 'list'
+ | 'enroll-select'
+ | 'enroll-details'
+ | 'verify'
+ | 'complete';
+
+type EnrollType = MfaFactorType;
+
// ========================================================================
// --- 1. HOOKS-BASED IMPLEMENTATION (Recommended) ---
// ========================================================================
@@ -29,7 +54,8 @@ const HooksAuthContent = (): React.JSX.Element => {
getCredentials,
createUser,
resetPassword,
- auth,
+ loginWithPasswordRealm,
+ mfa,
users,
} = useAuth0();
@@ -38,6 +64,37 @@ const HooksAuthContent = (): React.JSX.Element => {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
+ // MFA wizard state
+ const [mfaToken, setMfaToken] = useState('');
+ const [mfaStep, setMfaStep] = useState('idle');
+ const [mfaLoading, setMfaLoading] = useState(false);
+ const [authenticators, setAuthenticators] = useState([]);
+ const [selectedAuthenticator, setSelectedAuthenticator] =
+ useState(null);
+ const [enrollType, setEnrollType] = useState(null);
+ const [enrollPhoneNumber, setEnrollPhoneNumber] = useState('');
+ const [enrollEmail, setEnrollEmail] = useState('');
+ const [enrollmentChallenge, setEnrollmentChallenge] =
+ useState(null);
+ const [challengeResult, setChallengeResult] =
+ useState(null);
+ const [verifyCode, setVerifyCode] = useState('');
+ const [verifyBindingCode, setVerifyBindingCode] = useState('');
+
+ const resetMfaWizard = () => {
+ setMfaStep('idle');
+ setAuthenticators([]);
+ setSelectedAuthenticator(null);
+ setEnrollType(null);
+ setEnrollPhoneNumber('');
+ setEnrollEmail('');
+ setEnrollmentChallenge(null);
+ setChallengeResult(null);
+ setVerifyCode('');
+ setVerifyBindingCode('');
+ setMfaLoading(false);
+ };
+
const runDemo = async (action: () => Promise) => {
setResult(null);
setApiError(null);
@@ -45,10 +102,128 @@ const HooksAuthContent = (): React.JSX.Element => {
const response = await action();
setResult(response ?? { success: true });
} catch (e) {
+ if (e instanceof MfaError) {
+ setApiError(e);
+ return;
+ }
setApiError(e as Error);
}
};
+ const handleMfaError = (e: unknown, fallbackMsg: string) => {
+ if (e instanceof MfaError) {
+ if (
+ e.type === MfaErrorCodes.EXPIRED_MFA_TOKEN ||
+ e.type === MfaErrorCodes.INVALID_MFA_TOKEN
+ ) {
+ setMfaToken('');
+ resetMfaWizard();
+ }
+ setApiError(e);
+ } else {
+ setApiError(e as Error);
+ }
+ };
+
+ const onMfaStart = async () => {
+ setMfaLoading(true);
+ setApiError(null);
+ try {
+ const list = await mfa.getAuthenticators({ mfaToken });
+ setAuthenticators(list);
+ setMfaStep('list');
+ } catch (e) {
+ handleMfaError(e, 'Failed to list authenticators.');
+ } finally {
+ setMfaLoading(false);
+ }
+ };
+
+ const onMfaSelectAuthenticator = async (auth: MfaAuthenticator) => {
+ setSelectedAuthenticator(auth);
+ setMfaLoading(true);
+ try {
+ const res = await mfa.challenge({ mfaToken, authenticatorId: auth.id });
+ setChallengeResult(res);
+ setMfaStep('verify');
+ } catch (e) {
+ handleMfaError(e, 'Challenge failed.');
+ setMfaStep('list');
+ } finally {
+ setMfaLoading(false);
+ }
+ };
+
+ const onMfaSelectEnrollType = (type: EnrollType) => {
+ setEnrollType(type);
+ if (type === MfaFactorType.OTP || type === MfaFactorType.PUSH) {
+ onMfaEnroll(type);
+ } else {
+ setMfaStep('enroll-details');
+ }
+ };
+
+ const onMfaEnroll = async (type?: EnrollType) => {
+ const factor = type || enrollType;
+ if (!factor) return;
+ setMfaLoading(true);
+ try {
+ let challenge: MfaEnrollmentChallenge;
+ if (factor === MfaFactorType.SMS) {
+ challenge = await mfa.enroll({
+ mfaToken,
+ factorType: MfaFactorType.SMS,
+ phoneNumber: enrollPhoneNumber,
+ });
+ } else if (factor === MfaFactorType.EMAIL) {
+ challenge = await mfa.enroll({
+ mfaToken,
+ factorType: MfaFactorType.EMAIL,
+ email: enrollEmail,
+ });
+ } else {
+ challenge = await mfa.enroll({ mfaToken, factorType: factor });
+ }
+ setEnrollmentChallenge(challenge);
+ setMfaStep('verify');
+ } catch (e) {
+ handleMfaError(e, 'Enrollment failed.');
+ } finally {
+ setMfaLoading(false);
+ }
+ };
+
+ const onMfaVerify = async () => {
+ setMfaLoading(true);
+ try {
+ let credentials;
+ const oobCode =
+ challengeResult?.oobCode ||
+ (enrollmentChallenge?.type === 'oob'
+ ? enrollmentChallenge.oobCode
+ : undefined);
+
+ if (oobCode) {
+ credentials = await mfa.verify({
+ mfaToken,
+ oobCode,
+ bindingCode: verifyBindingCode || undefined,
+ });
+ } else {
+ credentials = await mfa.verify({ mfaToken, otp: verifyCode });
+ }
+ setResult({
+ success: true,
+ accessToken: credentials.accessToken.substring(0, 20) + '...',
+ });
+ setMfaStep('complete');
+ } catch (e) {
+ handleMfaError(e, 'Verification failed.');
+ } finally {
+ setMfaLoading(false);
+ }
+ };
+
if (isLoading) {
return (
@@ -91,9 +266,9 @@ const HooksAuthContent = (): React.JSX.Element => {
title="Log In"
/>
-
+
{
onChangeText={setPassword}
secureTextEntry
/>
+
-
-