Multi-Factor Authentication Webauthn screen classes

MFA Webauthn Change Key Nickname screen class

The MFA Webauthn Change Key Nickname screen class provides methods associated with the mfa-webauthn-change-key-nickname screen.

Import and instantiate the MFA Webauthn Change Key Nickname screen class:

import MfaWebAuthnChangeKeyNickname from "@auth0/auth0-acul-js/mfa-webauthn-change-key-nickname";
const mfaWebAuthnChangeKeyNicknameManager = new MfaWebAuthnChangeKeyNickname();

Properties

The MFA Webauthn Change Key Nickname screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Change Key Nickname screen class methods is:

continueWithNewNickname( options? )

This method submits the new nickname provided by the user for their WebAuthn security key.

const mfaWebAuthnChangeKeyNickname = new MfaWebAuthnChangeKeyNickname();
mfaWebAuthnChangeKeyNickname.continueWithNewNickname({
 nickname: 'string'
});

Parameter	Type	Required	Description
nickname	string	Yes	The nickame entered by the user.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

MFA Webauthn Enrollment Success screen class

The MFA Webauthn Enrollment Success screen class provides methods associated with the mfa-webauthn-enrollment-success screen.

Import and instantiate the MFA Webauthn Enrollment Success screen class:

import MfaWebAuthnEnrollmentSuccess from "@auth0/auth0-acul-js/mfa-webauthn-enrollment-success";
const mfaWebAuthnEnrollmentSuccessManager = new MfaWebAuthnEnrollmentSuccess();

Properties

The MFA Webauthn Enrollment Success screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Enrollment Success screen class methods is:

continue( options? )

This method allows the user to continue the authentication flow after a successful WebAuthn enrollment.

// Assuming 'mfaWebAuthnEnrollmentSuccessManager' is an instance of MfaWebAuthnEnrollmentSuccess
async function handleContinueClick() {
  try {
    await mfaWebAuthnEnrollmentSuccessManager.continue();
    // User will be redirected by Auth0.
  } catch (error) {
    console.error("Error continuing after WebAuthn enrollment success:", error);
    // Display error message to the user, potentially from mfaWebAuthnEnrollmentSuccessManager.transaction.errors
  }
}

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

MFA Webauthn Error screen class

The MFA Webauthn Error screen class provides methods associated with the mfa-webauthn-error screen.

Import and instantiate the MFA Webauthn Error screen class:

import MfaWebAuthnError from "@auth0/auth0-acul-js/mfa-webauthn-error";
const mfaWebAuthnErrorManager = new MfaWebAuthnError();

Properties

The MFA Webauthn Error screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Error screen class methods are:

noThanks( options? )

This method allows the user to decline the current WebAuthn operation (e.g., refuse to add a device during enrollment).

const mfaWebAuthnErrorManager = new MfaWebAuthnError();
await mfaWebAuthnErrorManager.noThanks();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

tryAgain( options? )

This method allows the user to retry the previous WebAuthn operation.

const mfaWebAuthnErrorManager = new MfaWebAuthnError();
await mfaWebAuthnErrorManager.tryagain();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

tryAnotherMethod( options? )

This method allows the user to choose a different Multi-Factor Authentication method.

const mfaWebAuthnErrorManager = new MfaWebAuthnError();
await mfaWebAuthnErrorManager.tryAnotherMethod();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

usePassword( options? )

This method allows the user to attempt authentication using their password, if this alternative is configured and appropriate for the current flow (e.g., if password was a prior authentication step or is a valid MFA bypass).

const mfaWebAuthnErrorManager = new MfaWebAuthnError();
await mfaWebAuthnErrorManager.usePassword();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

MFA Webauthn Not Available Error screen class

The MFA Webauthn Not Available Error screen class provides methods associated with the mfa-webauthn-platform-not-available-error screen.

Import and instantiate the MFA Webauthn Not Available Error screen class:

import MfaWebAuthnNotAvailableError from "@auth0/auth0-acul-js/mfa-webauthn-not-available-error";
const mfaWebAuthnNotAvailableErrorManager = new MfaWebAuthnNotAvailableError();

Properties

The MFA Webauthn Not Available Error screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Platform Challenge screen class methods are:

getError( options? )

This method retrieves the array of transaction errors from context or an empty array if none exist.

const mfaWebAuthnNotAvailableErrorManager = new MfaWebAuthnNotAvailableError();
await mfaWebAuthnNotAvailableErrorManager.getError();

tryAnotherMethod( options? )

This method allows the user to try another MFA method. This corresponds to the “Try Another Method” button.

const mfaWebAuthnNotAvailableErrorManager = new MfaWebAuthnNotAvailableError();

try {
  await mfaWebAuthnNotAvailableErrorManager.tryAnotherMethod();
  // On success, Auth0 typically handles redirection to the MFA factor selection screen.
} catch (error) {
  console.error('Failed to initiate "try another method":', error);
  // Update UI to inform the user about the failure to switch methods.
}

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

MFA Webauthn Platform Challenge screen class

The MFA Webauthn Platform Challenge screen class provides methods associated with the mfa-webauthn-platform-challenge screen.

Import and instantiate the MFA Webauthn Platform Challenge screen class:

import MfaWebAuthnPlatformChallenge from "@auth0/auth0-acul-js/mfa-webauthn-platform-challenge";
const mfaWebAuthnPlatformChallengeManager = new MfaWebAuthnPlatformChallenge();

Properties

The MFA Webauthn Platform Challenge screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Platform Challenge screen class methods are:

reportBrowserError( options? )

This method reports a browser-side error encountered during the WebAuthn navigator.credentials.get() operation. It sends the error details to the server with a specific action format.

const mfaWebAuthnPlatformChallengeManager = new MfaWebAuthnPlatformChallenge();
await mfaWebAuthnPlatformChallengeManager.reportBrowserError( {
  error: 'message'
});

Parameter	Type	Required	Description
error	message: string | name: string	Yes	The error object from the WebAuthn API (navigator.credentials.get()) to be reported.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

tryAnotherMethod( options? )

This method allows the user to opt-out of the WebAuthn platform challenge and select a different MFA method.

const mfaWebAuthnPlatformChallengeManager = new MfaWebAuthnPlatformChallenge();
await mfaWebAuthnPlatformChallengeManager.tryAnotherMethod();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

verify( options? )

This method initiates the WebAuthn platform authenticator challenge.

const mfaWebAuthnPlatformChallengeManager = new MfaWebAuthnPlatformChallenge();
await mfaWebAuthnPlatformChallengeManager.verify();

Parameter	Type	Required	Description
rememberDevice	boolean	No	Remember the browser for future MFA challenges. Corresponds to the rememberBrowser form field. This is only applicable if screen.showRememberDevice is true.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

MFA Webauthn Platform Enrollment screen class

The MFA Webauthn Platform Enrollment screen class provides methods associated with the mfa-webauthn-platform-enrollment screen.

Import and instantiate the MFA Webauthn Platform Enrollment screen class:

import MfaWebAuthnPlatformEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-platform-enrollment";
const mfaWebAuthnPlatformEnrollmentManager = new MfaWebAuthnPlatformEnrollment();

Properties

The MFA Webauthn Platform Enrollment screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Platform Enrollment screen class methods are:

refuseEnrollmentOnThisDevice( options? )

This method allows the user to refuse WebAuthn platform enrollment on the current device.

const mfaWebAuthnPlatformEnrollmentManager = new MfaWebAuthnPlatformEnrollment();
    mfaWebAuthnPlatformEnrollmentManager.refuseEnrollmentOnThisDevice();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

reportBrowserError( options? )

This method reports a browser-side error encountered during the WebAuthn navigator.credentials.create() operation.

const mfaWebAuthnPlatformEnrollmentManager = new MfaWebAuthnPlatformEnrollment();
await mfaWebAuthnPlatformEnrollmentManager.reportBrowserError( {
  error: 'message'
});

Parameter	Type	Required	Description
error	message: string | name: string	Yes	The error object from the WebAuthn API (navigator.credentials.get()) to be reported.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

snoozeEnrollment( options? )

This method allows the user to choose to snooze the WebAuthn platform enrollment.

const mfaWebAuthnPlatformEnrollmentManager = new MfaWebAuthnPlatformEnrollment();
    mfaWebAuthnPlatformEnrollmentManager.snoozeEnrollment();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

submitPasskeyCredential( options? )

This method initiates the WebAuthn platform credential creation process using the public key options available on this.screen.publicKey and submits the resulting credential to the server. This method internally calls createPasskeyCredentials (which wraps navigator.credentials.create()).

const mfaWebAuthnPlatformEnrollmentManager = new MfaWebAuthnPlatformEnrollment();

    try {
  await mfaWebAuthnPlatformEnrollmentManager.submitPasskeyCredential(); // No need to pass publicKey explicitly
  // On success, Auth0 handles redirection.
} catch (error) {
  console.error('Passkey enrollment failed:', error);
  if (error.name && error.message) { // Check if it looks like a WebAuthn error
    await mfaWebAuthnPlatformEnrollmentManager.reportBrowserError({ error: { name: error.name, message: error.message } });
  }
}

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

MFA Webauthn Roaming Challenge screen class

The MFA Webauthn Roaming Challenge screen class provides methods associated with the mfa-webauthn-roaming-challenge screen.

Import and instantiate the MFA Webauthn Roaming Challenge screen class:

import MfaWebAuthnRoamingChallenge from "@auth0/auth0-acul-js/mfa-webauthn-roaming-challenge";
const mfaWebAuthnRoamingChallengeManager = new MfaWebAuthnRoamingChallenge();

Properties

The MFA Webauthn Roaming Challenge screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Roaming Challenge screen class methods are:

reportWebauthn( options? )

This method reports a specific WebAuthn API error to Auth0. This method should be used if navigator.credentials.get() fails in a way that verify() does not automatically handle, or if the developer wants to explicitly report an error before trying another action. It submits the error details with action: "showError::{errorDetails}".

try {
  await mfaWebAuthnRoamingChallengeManager.reportWebAuthnError({
    error: { name: webAuthnError.name, message: webAuthnError.message }
  });
} catch (submitError) {
  console.error("Failed to report WebAuthn error:", submitError);
}

Parameter	Type	Required	Description
error	message: string | name: string	Yes	The error object from the WebAuthn API (navigator.credentials.get()) to be reported.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

tryAnotherMethod( options? )

This method allows the user to opt-out of the WebAuthn challenge and select a different MFA method.

try {
  await mfaWebAuthnRoamingChallengeManager.tryAnotherMethod();
  // On success, Auth0 handles redirection to MFA selection.
} catch (error) {
  console.error("Failed to switch MFA method:", error);
}

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

verify( options? )

This method initiates the WebAuthn platform authenticator challenge by calling navigator.credentials.get() with the options provided in screen.data.publicKeyChallengeOptions.

try {
  await mfaWebAuthnRoamingChallengeManager.verify({ rememberDevice: true });
  // On success, Auth0 handles redirection.
} catch (error) {
  console.error("Security key verification failed:", error);
  // Check mfaWebAuthnRoamingChallengeManager.transaction.errors for server-side validation messages if the page reloads.
}

Parameter	Type	Required	Description
rememberDevice	boolean	No	Remember the browser for future MFA challenges. Corresponds to the rememberBrowser form field. This is only applicable if screen.showRememberDevice is true.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

MFA Webauthn Roaming Enrollment screen class

The MFA Webauthn Roaming Enrollment screen class provides methods associated with the mfa-webauthn-roaming-enrollment screen.

Import and instantiate the MFA Webauthn Roaming Enrollment screen class:

import MfaWebAuthnRoamingEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment";
const mfaWebAuthnRoamingEnrollmentManager = new MfaWebAuthnRoamingEnrollment();

Properties

The MFA Webauthn Roaming Enrollment screen class properties are:

branding

interface branding {
  settings: null | BrandingSettings;
  themes: null | BrandingThemes;
}

interface BrandingSettings {
  colors?: {
    pageBackground?: string | {
      angleDeg: number;
      end: string;
      start: string;
      type: string;
    };
    primary?: string;
  };
  faviconUrl?: string;
  font?: {url: string;};
  logoUrl?: string;
}

interface BrandingThemes {
  default: {
    borders: Record<string, string | number | boolean>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}

Methods

The MFA Webauthn Roaming Enrollment screen class methods are:

enroll( options? )

This method initiates the WebAuthn credential creation and submits the result to the server. This corresponds to the user interacting with the FIDO Security Keys prompt.

import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
// Assuming you have obtained the WebAuthn credential response (e.g., from navigator.credentials.create)
const credentialResponse = { /* ... serialized credential ... */ };
await webauthnEnrollment.enroll({ response: JSON.stringify(credentialResponse) });

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.

showError( options? )

This method submits details about a WebAuthn browser error to the server. This is used when the browser’s WebAuthn API encounters an error.

import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
await webauthnEnrollment.showError({
  error: {
    name: 'NotAllowedError',
    message: 'The operation either timed out or was not allowed.',
  },
});

Parameter	Type	Required	Description
error	message: string | name: string	Yes	The error object from the WebAuthn API (navigator.credentials.get()) to be reported.
[key: string]	string | number | boolean | undefined	No	Additional data collected from the user.

tryAnotherMethod( options? )

This method allows the user to try another MFA method. This corresponds to the “Try Another Method” button.

import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
await webauthnEnrollment.tryAnotherMethod();

Parameter	Type	Required	Description
[key: string]	string | number | boolean | undefined	No	Optional data collected from user.