# Lockout policies

Mosaic supports lockout policies to protect against brute-force attacks and unauthorized access.

All authenticators support a **simple lockout** policy, where after the lockout period expires, the user can retry authentication with a fresh attempt counter.

**Passkeys**, **Passwords (new implementation only)**, **TOTP**, **Face authentication**, and **PIN codes** support **progressive lockout tiers**, providing enhanced security through escalating lockout durations that deter brute-force attacks.

## Simple lockout

A simple lockout uses a single threshold:

- After a configured number of **failed attempts**
- The authenticator is locked for a fixed **lockout duration** (in minutes)


After the lockout period expires, the user can retry authentication with a fresh attempt counter.

**Example:**

- After 3 failed attempts → Locked for 15 minutes
- After the lockout period expires, the user can try again with a fresh set of attempts


## Progressive lockout tiers

Note
Available for **Passkeys**, **Passwords (new implementation only)**, **TOTP**, **Face authentication**, and **PIN codes**.

For **Passwords**, this is a backwards-compatible (non-regressive) change: tenants using the legacy password authenticator continue to use the existing simple lockout behavior (no tiers).

Progressive lockout tiers apply **escalating lockout durations** based on consecutive failed attempts. You can configure up to 10 tiers.

Each tier include:

- **Attempts** — total number of consecutive failures required to trigger the tier (the count is cumulative and does not reset between tiers)
- **Duration** — lockout time in minutes for lockout. **Users are automatically unlocked after each lockout period**.


In addition, progressive tiers use a **failed-attempt counting window** (`failuresExpireIn`, in minutes). This window determines how long failed attempts are counted as consecutive:

- Only failed attempts within the last X minutes (where X is the `failuresExpireIn` value) are counted as consecutive.
- If X minutes pass since the last failed attempt, all previous failed attempts expire and are no longer counted, and the attempt counter resets.


Permanent lock
After all configured tiers are exhausted, additional consecutive failures result in a **permanent lock** that requires admin intervention via the [Unlock authenticators API](/openapi/user/authenticators.openapi/other/unlockuserauthenticator). For details about lockout settings, see [Customize login methods](/guides/user/auth_methods_customize).

You can configure progressive lockout tiers:

- In the **Admin Portal** > **B2C** or **B2B Identity** *based on your setup* > **Authentication methods** > **Passwords**, **TOTP**, **Passkeys**, **Face authentication**, or **PIN codes**. See [Customize login methods](/guides/user/auth_methods_customize).
- You can also manage lockout settings using the [Login Preferences API](/openapi/user/login-preferences.openapi/other/updateappauthmethods). API support for lockout tiers depends on the authenticator—refer to the API schema for the supported fields.


**Example**

This example demonstrates a progressive lockout configuration with three tiers:

div
img
- after first three failed attempts, users are locked for 2 minutes
- after fourth failed attempt, 5 minutes
- after fifth failed attempt, 15 minutes
- in case of sixth failed attempt, permanent lock


The failed-attempt counting window is set to 30 minutes, meaning only failed attempts within the last 30 minutes are counted as consecutive. This ensures that when the Tier 3 lockout (15 minutes) expires, the previous failed attempts are still within the counting window and continue to be counted.

This translates into the following user flow:


```mermaid
sequenceDiagram
    participant User
    participant App

    User->>App: Attempt 1 (wrong password)
    App->>User: Invalid

    User->>App: Attempt 2 (wrong password)
    App->>User: Invalid

    User->>App: Attempt 3 (wrong password)
    App->>User: Locked 

    Note over User,App: Tier 1 — 2 min wait

    User->>App: Attempt 4 (wrong password)
    App->>User: Locked

    Note over User,App: Tier 2 — 5 min wait

    User->>App: Attempt 5 (wrong password)
    App->>User: Locked 

    Note over User,App: Tier 3 — 15 min wait

    User->>App: Attempt 6
    alt Correct password
        App->>User: Success
    else Wrong password
        App->>User: Permanent lockout
    end
```