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

## 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 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](/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. Use the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator) to unlock locked passkey authenticators.


## 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. Use the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator) to unlock locked password authenticators.


## 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, and unlocking affects the OTP usage in every application. Use the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator) to unlock locked OTP authenticators.


## 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. 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).
- Unlocking affects only the specific app instance where the authenticator is locked. Use the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator) to unlock locked TOTP authenticators.


## 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. Use the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator) to unlock locked PIN authenticators.


style

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