feat: support MFA step-up authentication via popup in iframe-based silent auth flow (#1540)

### Summary

Extend `interactiveErrorHandler: 'popup'` to handle MFA step-up errors
from the iframe path. Previously, step-up only worked with refresh
tokens. The iframe path returned `login_required` (not `mfa_required`),
which caused a premature `logout()` and was not detected as an
interactive error. Now both token acquisition paths trigger the popup
automatically.

Extends step-up functionality added in
#1531

### Changes

- Detect iframe MFA step-up errors by matching `error='login_required'`
+ `error_description='Multifactor authentication required'`
- Widen interactive error detection to match both `MfaRequiredError`
(refresh tokens) and the iframe `GenericError` variant
- Skip `logout()` when the `login_required` error is an MFA step-up and
the handler is configured, preserving the session for the popup
- Add two tests: popup opens on iframe MFA error, and `logout()` is not
called
- Remove internal jargon ("iframe flow", "refresh token flow") from
user-facing step-up docs

### Example

```js
// Works with or without useRefreshTokens — no change needed
const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  interactiveErrorHandler: 'popup'
});

// If MFA is required, popup opens automatically
const token = await auth0.getTokenSilently({
  authorizationParams: {
    audience: 'https://api.example.com',
    scope: 'read:sensitive-data'
  }
});
```

### Testing

- Added two new tests to cover the recent changes  
- All tests are passing  
- `npm run build` completes successfully  
- Performed manual testing using `static/step-up.html`: reproduced the
iframe-based silent token flow with MFA step-up and confirmed that the
popup appears and successfully returns a token

Author: gyaneshgouraw-okta

EXAMPLES.md

@@ -1208,22 +1208,19 @@ try {
 
 Step-up authentication lets you request elevated access for sensitive operations (e.g. a specific audience or scope) and automatically handle MFA challenges via a popup, without manually catching errors or managing the MFA API.
 
-When `getTokenSilently()` encounters an `mfa_required` error and `interactiveErrorHandler` is configured, the SDK automatically opens a Universal Login popup to complete MFA, then returns the token.
-
-> [!NOTE]
-> The interactive error handler currently only handles `mfa_required` errors. Other interactive errors (e.g. `login_required`, `consent_required`) are not intercepted and will be thrown to the caller as usual.
+When `getTokenSilently()` encounters an MFA step-up error and `interactiveErrorHandler` is configured, the SDK automatically opens a Universal Login popup to complete MFA, then returns the token. This works regardless of whether you use refresh tokens (`useRefreshTokens: true`) or the default configuration.
 
 ### Setup
 
-Enable the interactive error handler when creating the client. Refresh tokens must also be enabled, since `mfa_required` errors originate from the refresh token exchange. This feature is most suitable when combined with [Multi-Resource Refresh Tokens (MRRT)](#using-multi-resource-refresh-tokens), which allow a single refresh token to obtain access tokens for multiple APIs — making step-up requests across different audiences seamless.
+Enable the interactive error handler when creating the client. Step-up authentication works with or without refresh tokens — no additional configuration is needed. When using refresh tokens, consider combining with [Multi-Resource Refresh Tokens (MRRT)](#using-multi-resource-refresh-tokens), which allow a single refresh token to obtain access tokens for multiple APIs — making step-up requests across different audiences seamless.
 
 ```js
 const auth0 = await createAuth0Client({
   domain: '<AUTH0_DOMAIN>',
   clientId: '<AUTH0_CLIENT_ID>',
-  useRefreshTokens: true,
-  useMrrt: true, //optional
   interactiveErrorHandler: 'popup',
+  useRefreshTokens: true, // optional — works with or without refresh tokens
+  useMrrt: true, // optional — useful when stepping up across multiple APIs
   authorizationParams: {
     redirect_uri: '<MY_CALLBACK_URL>'
   }
@@ -1279,7 +1276,7 @@ try {
 ```
 
 > [!NOTE]
-> If `interactiveErrorHandler` is not configured, `MfaRequiredError` is thrown as usual, and you can handle it manually using the [MFA API](#multi-factor-authentication-mfa).
+> If `interactiveErrorHandler` is not configured, MFA errors are thrown to the caller as usual. When using refresh tokens, you can handle `MfaRequiredError` manually using the [MFA API](#multi-factor-authentication-mfa).
 
 > [!IMPORTANT]
 > `interactiveErrorHandler` only affects `getTokenSilently()`. Other methods like `loginWithPopup()` and `loginWithRedirect()` are not affected.

__tests__/Auth0Client/interactiveErrorHandler.test.ts

@@ -23,7 +23,8 @@ import {
   TEST_TOKEN_TYPE
 } from '../constants';
 
-import { MfaRequiredError } from '../../src/errors';
+import { GenericError, MfaRequiredError } from '../../src/errors';
+import { MFA_STEP_UP_ERROR_DESCRIPTION } from '../../src/constants';
 
 jest.mock('es-cookie');
 jest.mock('../../src/jwt');
@@ -325,5 +326,108 @@ describe('Auth0Client', () => {
         expect(utils.runPopup).not.toHaveBeenCalled();
       });
     });
+
+    describe('iframe flow', () => {
+      it('should open popup when iframe returns MFA step-up error', async () => {
+        const auth0 = setup({
+          interactiveErrorHandler: 'popup',
+        });
+
+        await loginWithRedirect(auth0, {
+          authorizationParams: {
+            audience: TEST_AUDIENCE,
+            scope: 'read:data'
+          }
+        });
+
+        mockFetch.mockReset();
+
+        // Mock runIframe to reject with MFA step-up error
+        jest.spyOn(<any>utils, 'runIframe').mockRejectedValue(
+          GenericError.fromPayload({
+            error: 'login_required',
+            error_description: MFA_STEP_UP_ERROR_DESCRIPTION
+          })
+        );
+
+        setupPopupMock(mockWindow, {
+          code: 'my_code',
+          state: TEST_STATE
+        });
+
+        // Token response from popup's code exchange
+        mockFetch.mockResolvedValueOnce(
+          fetchResponse(true, {
+            id_token: TEST_ID_TOKEN,
+            refresh_token: TEST_REFRESH_TOKEN,
+            access_token: TEST_ACCESS_TOKEN,
+            token_type: TEST_TOKEN_TYPE,
+            expires_in: 86400
+          })
+        );
+
+        const token = await auth0.getTokenSilently({
+          authorizationParams: {
+            audience: TEST_AUDIENCE,
+            scope: 'read:data'
+          },
+          cacheMode: 'off'
+        });
+
+        expect(token).toBeTruthy();
+        expect(utils.runPopup).toHaveBeenCalled();
+      });
+
+      it('should not call logout when handler is configured and error is iframe MFA step-up', async () => {
+        const auth0 = setup({
+          interactiveErrorHandler: 'popup'
+        });
+
+        await loginWithRedirect(auth0, {
+          authorizationParams: {
+            audience: TEST_AUDIENCE,
+            scope: 'read:data'
+          }
+        });
+
+        mockFetch.mockReset();
+
+        jest.spyOn(auth0, 'logout');
+
+        // Mock runIframe to reject with MFA step-up error
+        jest.spyOn(<any>utils, 'runIframe').mockRejectedValue(
+          GenericError.fromPayload({
+            error: 'login_required',
+            error_description: MFA_STEP_UP_ERROR_DESCRIPTION
+          })
+        );
+
+        setupPopupMock(mockWindow, {
+          code: 'my_code',
+          state: TEST_STATE
+        });
+
+        // Token response from popup's code exchange
+        mockFetch.mockResolvedValueOnce(
+          fetchResponse(true, {
+            id_token: TEST_ID_TOKEN,
+            refresh_token: TEST_REFRESH_TOKEN,
+            access_token: TEST_ACCESS_TOKEN,
+            token_type: TEST_TOKEN_TYPE,
+            expires_in: 86400
+          })
+        );
+
+        await auth0.getTokenSilently({
+          authorizationParams: {
+            audience: TEST_AUDIENCE,
+            scope: 'read:data'
+          },
+          cacheMode: 'off'
+        });
+
+        expect(auth0.logout).not.toHaveBeenCalled();
+      });
+    });
   });
 });

src/Auth0Client.ts

@@ -57,6 +57,7 @@ import {
   DEFAULT_POPUP_CONFIG_OPTIONS,
   DEFAULT_AUTHORIZE_TIMEOUT_IN_SECONDS,
   MISSING_REFRESH_TOKEN_ERROR_MESSAGE,
+  MFA_STEP_UP_ERROR_DESCRIPTION,
   DEFAULT_SCOPE,
   DEFAULT_SESSION_CHECK_EXPIRY_DAYS,
   DEFAULT_AUTH0_CLIENT,
@@ -926,10 +927,29 @@ export class Auth0Client {
 
   /**
    * Checks if an error should be handled by the interactive error handler.
-   * Currently only handles mfa_required; extensible for future error types.
+   * Matches:
+   * - MfaRequiredError (refresh token path, error='mfa_required')
+   * - GenericError from iframe path (error='login_required',
+   *   error_description='Multifactor authentication required')
+   * Extensible for future interactive error types.
    */
-  private _isInteractiveError(error: unknown): error is MfaRequiredError {
-    return error instanceof MfaRequiredError;
+  private _isInteractiveError(
+    error: unknown
+  ): error is MfaRequiredError | GenericError {
+    return error instanceof MfaRequiredError || (error instanceof GenericError && this._isIframeMfaError(error));
+  }
+
+  /**
+   * Checks if a login_required error from the iframe flow is actually
+   * an MFA step-up requirement. The /authorize endpoint returns
+   * error='login_required' with error_description='Multifactor authentication required'
+   * when MFA is needed but prompt=none prevents interaction.
+   */
+  private _isIframeMfaError(error: GenericError): boolean {
+    return (
+      error.error === 'login_required' &&
+      error.error_description === MFA_STEP_UP_ERROR_DESCRIPTION
+    );
   }
 
   /**
@@ -1207,9 +1227,19 @@ export class Auth0Client {
       );
     } catch (e) {
       if (e.error === 'login_required') {
-        this.logout({
-          openUrl: false
-        });
+        // When the login_required error is actually an MFA step-up requirement
+        // and the interactive error handler is configured, skip logout so the
+        // session is preserved for the popup flow.
+        const shouldSkipLogoutForMfaStepUp =
+          e instanceof GenericError &&
+          this._isIframeMfaError(e) &&
+          this.options.interactiveErrorHandler === 'popup';
+
+        if (!shouldSkipLogoutForMfaStepUp) {
+          this.logout({
+            openUrl: false
+          });
+        }
       }
       throw e;
     }

src/constants.ts

@@ -46,6 +46,13 @@ export const INVALID_REFRESH_TOKEN_ERROR_MESSAGE = 'invalid refresh token';
  */
 export const USER_BLOCKED_ERROR_MESSAGE = 'user is blocked';
 
+/**
+ * @ignore
+ * The error_description returned by the /authorize endpoint when MFA is required
+ * but prompt=none prevents interaction (iframe silent auth flow).
+ */
+export const MFA_STEP_UP_ERROR_DESCRIPTION = 'Multifactor authentication required';
+
 /**
  * @ignore
  */