# 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](/guides/user/manage_authenticators)

For detailed information about lockout policies, including progressive lockout tiers, see [Lockout policies](/guides/user/auth_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](/guides/user/auth_lockout_policies).


Note
- Face authentication is scoped per app. Each application manages its own face authenticator configuration and status for the user. For more about authenticator scoping models (global, per app, or per device), see [Manage authenticators](/guides/user/manage_authenticators).
- You can unlock locked face authenticators in the [Admin Portal](/guides/user/manage_authenticators#manage-authenticator-status) or using the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator).


## Passkeys

Important
To use passkeys, make sure you’ve integrated the appropriate SDK for your platform: [Android SDK quick start](/guides/webauthn/quick_start_sdk_android), [Web SDK quick start](/guides/webauthn/quick_start_sdk), or [iOS SDK quick start](/guides/webauthn/quick_start_sdk_ios).

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's 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 the Base64-encoded SHA-256 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.
- **Passkey attestation**: configure which passkey types are allowed, whether cryptographic attestation is required, and which authenticator models are permitted or blocked.
  - **Allow synced passkeys**: controls whether passkeys that sync across devices, such as Apple iCloud Keychain or Google Password Manager, are allowed.
  - **Attestation preference**: defines the attestation type Mosaic requests during registration:
    - **None** (default): no attestation is requested. Privacy-first and backward compatible.
    - **Direct**: explicitly requests attestation from the authenticator.
    - **Indirect**: requests attestation-compatible metadata with broader interoperability.
  - **Enforce passkey attestation**: requires valid attestation for device-bound passkeys during registration. This does not apply to synced passkeys. When **Enforce passkey attestation** is enabled, Mosaic sets **Attestation preference** to **Direct** and the field cannot be changed.
  - **AAGUID restrictions**: control which authenticator models are allowed, based on their AAGUID (Authenticator Attestation GUID). Use an **Allow list** to permit only the listed AAGUIDs, or a **Block list** to deny them.
For details about passkey types, attestation enforcement, and retroactive effects, see [Passkey attestation](/guides/user/passkey_attestation).
- **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](/guides/user/auth_lockout_policies).


Note
- Passkeys are device-based authenticators scoped per device per app. For more about authenticator scoping models (global, per app, or per device), see [Manage authenticators](/guides/user/manage_authenticators).
- Unlocking applies per app and resets the lockout status for all passkeys registered by the user in that app. You can unlock locked passkey authenticators in the [Admin Portal](/guides/user/manage_authenticators#manage-authenticator-status) or using the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator).
- You can also configure passkey attestation settings using the [Login Preferences API](/openapi/user/login-preferences.openapi/other/updateappauthmethods).


## 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](/guides/user/auth_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.

Note
- Passwords are scoped per app. Each application manages its own password configuration and status for the user. For more about authenticator scoping models (global, per app, or per device), see [Manage authenticators](/guides/user/manage_authenticators).
- Unlocking applies only to the specific app where the password is locked. You can unlock locked password authenticators in the [Admin Portal](/guides/user/manage_authenticators#manage-authenticator-status) or using the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator).


## 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.


Note
The **From** field displays the value of **Application name** (as configured in the app settings) as the sender. This value cannot be modified.

## 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](/guides/user/auth_lockout_policies#simple-lockout).
- **Cross-client OTP flow**: enable this setting to allow one client to initiate OTP generation while a different client submits it. This is required to use the [Generate temporary access code](/guides/user/account_recovery) feature in the Admin Portal.


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.

Note
- Email and SMS OTPs are tenant-wide authenticators. For more about authenticator scoping models (global, per app, or per device), see [Manage authenticators](/guides/user/manage_authenticators).
- Their lockout status applies across all apps. OTP authenticators cannot be locked, unlocked, or deleted via the Admin Portal or API.


## 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](/guides/user/be_auth_totp)

- **Max TOTPs**: the maximum number of TOTP authenticators a user can have at the same time. You can set any whole number from 1 to 50. 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](/guides/user/auth_lockout_policies).


Note
Modifying the following values can cause compatibility issues with public authenticator apps.

- **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`.


Note
- TOTP authenticators are scoped per app. A user may have separate TOTP credentials in different applications. For more about authenticator scoping models (global, per app, or per device), see [Manage authenticators](/guides/user/manage_authenticators).
- TOTP authenticators cannot be locked or unlocked via the Admin Portal or API. You can [delete TOTP authenticators](/guides/user/manage_authenticators#manage-authenticator-status) from the Admin Portal or using the [User Authenticators API](/openapi/user/authenticators.openapi/other/userauthenticators).


## 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](/guides/user/auth_lockout_policies).


Note
- PIN codes are scoped per device per app. This means a user can:
  - Register different PINs for the same app on different devices.
  - Register different PINs for different apps on the same device.
  - Use the same PIN value across apps or devices, but each registration is distinct and independently managed.
For more about authenticator scoping models (global, per app, or per device), see [Manage authenticators](/guides/user/manage_authenticators).
- Unlocking applies per app and resets the lockout status for all registered PINs of the user in that app. You can unlock locked PIN authenticators in the [Admin Portal](/guides/user/manage_authenticators#manage-authenticator-status) or using the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator).


style

    section article ul li {
        margin-top: 5px !important;
    }