Customize login methods

Mosaic allows you to customize how users authenticate across the apps in your tenant. You can define which authenticators are available per app, configure their behavior and lockout policy, and control how authentication status is tracked and managed across apps and devices (Admin Portal > B2C or B2B Identity based on your setup > Authentication Methods).

To learn how to manage and strategize with authenticators, see Manage authenticators

For detailed information about lockout policies, including progressive lockout tiers, see Lockout policies.

Face authentication

Face authentication lets users log in by verifying their identity with a live selfie, matched against a securely stored reference image. It provides a fast and seamless login experience while ensuring strong protection against fraud.

You can configure the following settings:

• Store face reference: allow storing digital code generated from facial features.

• Lockout: configure how failed face authentication attempts are handled. You can use either:

  • Counting Window: configure the Failed-attempt counting window to define the time period (in minutes) for counting consecutive failed attempts.
  • Lockout Tiers: configure up to 10 tiers with escalating lockout durations. Each tier includes:
    • Failed attempts: the number of failed attempts that trigger this tier
    • Lockout duration: the lockout duration in minutes

  For detailed information, see Lockout policies.

Passkeys

Passkeys let users authenticate with device-based authenticators such as Apple Touch ID, Windows Hello, or hardware security keys. They offer a seamless and phishing-resistant login experience.

• Relying Party ID: define the domain to which WebAuthn credentials are registered and used for authentication. Set it to your application’s domain (e.g., example.com). Mosaic accepts any origin that matches this domain, including all subdomains.

• Relying Party Origins: toggle this option to specify platform-specific origins.

  • Web: toggle the Relying Party Origins to restrict usage to specific subdomains. Add one or more subdomains of the Relying Party ID, ensuring to provide the full URL.
  • iOS: use ios:bundle-id:YOUR_APP_BUNDLE_ID, where YOUR_APP_BUNDLE_ID is your iOS app unique identifier. This is the origin that will be provided when requesting passkeys registration and authentication.
  • Android use android:apk-key-hash:YOUR_APK_KEY_HASH, where YOUR_APK_KEY_HASH is your base64 encoded sha256 hash of your apk signing certificate. This is the origin that will be provided when requesting passkeys registration and authentication.

• Enforce single passkey per ecosystem: when enabled, each username will have only one active passkey per ecosystem (Apple or Android). Registering a new passkey replaces any existing one within the same ecosystem.

• Lockout: configure how failed passkey authentication attempts are handled. You can use either:

  • Counting Window: configure the Failed-attempt counting window to define the time period (in minutes) for counting consecutive failed attempts.
  • Lockout Tiers: configure up to 10 tiers with escalating lockout durations. Each tier includes:
    • Failed attempts: the number of failed attempts that trigger this tier
    • Lockout duration: the lockout duration in minutes

  For detailed information, see Lockout policies.

Passwords

The password settings let you define your app’s password policy:

• Complexity: configure the strength of your password policy by selecting requirements such as uppercase and lowercase letters, special characters, numbers, and more. The UI provides guidance as you select the appropriate options.

• Expiration: set the password expiration policy. You can define an expiration period (in days), or choose to let passwords never expire. Enabling Allow password to never expire overrides the Expiration time setting. The UI provides guidance as you select the appropriate options.

• Password history: control whether users can reuse recent passwords. When enabled, it prevents the reuse of past passwords and activates the Number of last passwords field, where you can define how many previous passwords to block.

• HIBP: prevent users from setting passwords that have been exposed in known data breaches, using the Have I Been Pwned (HIBP) service.

• Dictionary: block passwords that appear in a predefined dictionary of weak or banned terms. The dictionary is managed by you via API.

• Lockout: configure how failed password attempts are handled. You can use either:

  • Counting Window: configure the Failed-attempt counting window to define the time period (in minutes) for counting consecutive failed attempts.
  • Lockout Tiers: configure up to 10 tiers with escalating lockout durations. Each tier includes:
    • Failed attempts: the number of failed attempts that trigger this tier
    • Lockout duration: the lockout duration in minutes
    • Availability: lockout tiers for Passwords are available only for the new password authenticator implementation.

  For detailed information, see Lockout policies.

• Password reset policy: configure the expiration time (in minutes) for password reset links, and the length of the reset OTP. You can also require MFA during password reset as an extra layer of security, and choose to send an email notification to the user when a password is updated.

• Temporary password: set how long temporary passwords remain valid (in hours).

Additionally, you can customize the appearance of the Reset password email by choosing a custom color to apply to buttons and dynamic content such as email addresses.

Email magic links

The email magic link settings let you configure the following:

• Set the validity period of the magic link in minutes (Expires in).
• Define the maximum number of magic links that can be sent to a user per minute (Allowed magic links to send a user per minute). If the threshold is reached, the API returns a 429 error indicating too many requests.
• Customize the Email template appearance by selecting a custom button color and dynamic content such as email addresses.

One-time passcodes

The one-time passcode settings let you define your OTP policy, regardless of the delivery method (email or SMS sent via Mosaic or external providers):

• Expiration time: set how long the OTP remains valid (in minutes).

• Code length: set the length of the one-time code.

• Lockout: configure the simple lockout policy:

  • Failed attempts allowed before lockout: set the number of failed attempts that trigger a temporary lockout.
  • Lockout duration: define how long the user must wait before they can try again.

  For detailed information, see Lockout policies.

The OTP emails section lets you customize the appearance of OTP emails by choosing a button color and dynamic content such as email addresses. You can also preview the login, sign-up, and verification email templates.

TOTP

Time-based one-time password (TOTP) authentication lets users log in with codes generated by authenticator apps such as Google Authenticator or Microsoft Authenticator. For implementation details, see Login with TOTP

• Max TOTPs: the maximum number of TOTP authenticators a user can have at the same time. When the limit is reached, new registrations are blocked.

• Issuer: the name of the app shown in the user's authenticator app. This field is pre-filled and not editable.

• Lockout: configure how failed TOTP code attempts are handled. You can use either:

  • Counting Window: define the time period (in minutes) for counting consecutive failed attempts.
  • Lockout Tiers: configure up to 10 tiers with escalating lockout durations. Each tier includes:
    • Failed attempts: the number of failed attempts that trigger this tier
    • Lockout duration: the lockout duration in minutes

  For detailed information, see Lockout policies.

• Window size: define how many token intervals before and after the current code are considered valid. Acceptable values range from 0 to 5.
• Hash algorithm: select the HMAC hash algorithm used to generate the tokens. Default: SHA-1.
• Token digits: set the length (in digits) of the generated token. Default: 6.
• Token period: define how long (in seconds) each TOTP code remains valid. Default: 30.

PIN codes

Mobile PIN authentication lets users log in to their app using a PIN code that they choose specifically for the app. This ensures a secure and user-controlled experience, while the credential remains protected by the device's security hardware.

You can configure the following settings:

• Lockout: configure how failed PIN attempts are handled. You can use either:

  • Counting Window: define the time period (in minutes) for counting consecutive failed attempts.
  • Lockout Tiers: configure up to 10 tiers with escalating lockout durations. Each tier includes:
    • Failed attempts: the number of failed attempts that trigger this tier
    • Lockout duration: the lockout duration in minutes

  For detailed information, see Lockout policies.