---
title: "Passkey Enforcement"
manual: "Passkeys Backend Authentication"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-passkeys-be:enforcement@1.0"
source: "Administration/Enforcement.rst"
rendered: "2026-09-20T16:07:13+00:00"
---

# Passkey Enforcement {#enforcement}

<!-- TODO: no Markdown rendering for "versionadded" -->

The extension supports per-group enforcement of passkey registration with
configurable grace periods. This allows administrators to gradually roll out
passkeys across their organisation -- from gentle encouragement to mandatory
adoption.

## Enforcement levels {#enforcement-levels}

Each backend user group can be assigned one of four enforcement levels. The
level controls how aggressively the extension prompts users to register a
passkey.

| Level | Severity | Behaviour |
| --- | --- | --- |
| **Off** | 0 | No prompts. Passkeys are fully optional. This is the default for all groups. |
| **Encourage** | 1 | A dismissible banner is shown to users who have not registered a passkey. The banner explains what passkeys are, why to set them up, links to the extension documentation, and provides administrator contact guidance. Users can dismiss the banner and continue working. |
| **Required** | 2 | An interstitial page appears after login for users without passkeys. During the grace period, users can click **Skip for now** to dismiss the interstitial for the remainder of their session. After the grace period expires, the interstitial becomes mandatory and cannot be skipped. In addition, once the grace period has expired, **password login is refused for users who already have a passkey** -- they must authenticate with their passkey (the same behaviour as **Enforced** for those users). If such a user loses access to their authenticator, see *Recovery procedures* below. |
| **Enforced** | 3 | The strictest level. Password login is disabled for users who already have passkeys. Users who have not yet registered a passkey see a mandatory interstitial after login with no skip option. |

> [!TIP]
> Start with **Encourage** for all groups. Once adoption reaches a
> comfortable level, move to **Required** with a generous grace period (e.g.
> 30 days). Only set **Enforced** after all users in the group have had time
> to register their passkeys.

## Configuring enforcement per group {#configuring-enforcement-per-group}

![Backend user group record showing Passkeys tab with enforcement dropdown and grace period field](../Images/Administration/GroupEnforcement.png)

Enforcement is configured on each backend user group record:

1.  Go to **System > Backend Users** and select the
    **Backend User Groups** list.
1.  Edit a group record.
1.  Switch to the **Passkeys** tab.
1.  Set the **Passkey Enforcement** dropdown to the desired level.
1.  If the level is **Required**, configure the **Grace Period (Days)**
    field (default: 14 days, range: 1--365).

> [!NOTE]
> The **Grace Period (Days)** field is only visible when the
> enforcement level is set to **Required**. The **Enforced** level has no
> grace period -- the interstitial is always mandatory.

## Grace period mechanics {#grace-period-mechanics}

The grace period gives users time to register a passkey before the requirement
becomes mandatory:

1.  An administrator sets a group to **Required** with a grace period (e.g. 14
    days).
1.  The first time a user in that group logs in and the interstitial middleware
    intercepts them, the grace period starts (a timestamp is recorded on the
    `be_users` record).
1.  During the grace period, the interstitial shows a countdown:
    *"You have N days remaining to set up your passkey."*
    The user can click **Skip for now** to dismiss the interstitial for
    the current session.
1.  When the grace period expires, the interstitial becomes mandatory. The skip
    button is no longer available and the user must register a passkey to
    continue.

> [!IMPORTANT]
> The grace period starts on the user's **first login** after their group
> moves to **Required**, not when the administrator changes the setting. Users
> who do not log in during the grace window will see the full grace period
> when they eventually log in.

The grace period start timestamp is stored in the `passkey_grace_period_start`
column on the `be_users` table.

## Multi-group resolution {#multi-group-resolution}

When a backend user belongs to multiple groups with different enforcement
settings, the extension resolves the effective level using two rules:

1.  **Strictest level wins.** If a user belongs to group A (Encourage) and
    group B (Required), the effective level is **Required**.
1.  **Shortest grace period wins among same-level groups.** If two groups are
    both set to Required but with different grace periods (group A: 30 days,
    group B: 14 days), the effective grace period is **14 days**.

**Multi-group resolution example**

```text
User belongs to:
  - Editors (Encourage, 0 days)      -> severity 1
  - Content Managers (Required, 30d) -> severity 2
  - Reviewers (Required, 14d)        -> severity 2

Effective: Required, 14-day grace period
```

Users with no group assignments default to enforcement level **Off**.

> [!NOTE]
> Enforcement considers only the groups **directly assigned** to a user
> (the `be_users.usergroup` field). TYPO3 subgroups (configured via
> `be_groups.subgroup`) are **not** resolved for enforcement evaluation.
> If you configure enforcement on a subgroup, assign that group directly to
> the affected users or configure enforcement on the parent group instead.

## Admin dashboard {#admin-dashboard}

![Full-page interstitial prompting user to set up a passkey with countdown and skip option](../Images/Administration/InterstitialPage.png)

The **Admin Tools > Passkey Management** module
provides a dashboard for monitoring and managing passkey
adoption across the organisation.

### Dashboard tab {#dashboard-tab}

The dashboard tab shows:

-   **Overall adoption statistics** -- A progress bar with the total number of
    backend users, how many have passkeys, and the adoption percentage.
-   **Per-group enforcement table** -- Each group is listed with its current
    enforcement level, grace period, member count, passkey adoption count, and
    adoption percentage. Administrators can change a group's enforcement level
    directly from the dropdown in the table.
-   **Users without passkeys** -- A list of users who have not yet registered a
    passkey, showing their username, real name, grace period start date, and
    remaining days. **Send reminder**, **Clear nudge**, and
    **Unlock** actions are available per user.

### Help tab {#help-tab}

The help tab provides:

-   **Rollout guide** -- Step-by-step instructions for rolling out passkeys
    across the organisation.
-   **Recovery procedures** -- What to do when a user loses their authenticator
    device.
-   **MFA coexistence** -- How passkey enforcement interacts with TYPO3's
    built-in MFA.
-   **FAQ** -- Answers to common questions about passkey enforcement.

## Monitoring adoption progress {#monitoring-adoption-progress}

Use the dashboard's adoption statistics to track rollout progress:

1.  Navigate to **Admin Tools > Passkey Management**.
1.  The progress bar at the top shows overall adoption (e.g. "12 of 25 users
    have passkeys -- 48%").
1.  Review the per-group table to identify groups with low adoption.
1.  Use the **Send reminder** action for individual users who have not
    yet registered.
1.  Use the **Unlock** action to reset rate-limiting
    for locked-out users.

> [!TIP]
> Before moving a group from **Required** to **Enforced**, verify that the
> group's adoption percentage is at or near 100% in the dashboard. Users
> without passkeys in an **Enforced** group will see a mandatory interstitial
> on every login until they register.

## Recovery procedures {#recovery-procedures}

When a user loses access to their authenticator device (e.g. a lost phone or
broken YubiKey):

1.  The user contacts an administrator.
1.  The administrator opens **Admin Tools > Passkey Management** or uses
    the admin API to **revoke** the affected credential:

    **Revoke a credential via admin API**

    ```text
    POST /typo3/ajax/passkeys/admin/remove
    Content-Type: application/json

    {"beUserUid": 123, "credentialUid": 456}
    ```
1.  If the user is locked out, the administrator can
    **unlock** the account:

    **Unlock a locked-out account**

    ```text
    POST /typo3/ajax/passkeys/admin/unlock
    Content-Type: application/json

    {"beUserUid": 123, "username": "johndoe"}
    ```

### Command-line recovery {#command-line-recovery}

If **all** administrators are locked out -- for example a group was set to
**Enforced** and every member lost access to their authenticator -- recovery is
still possible from the server shell, without a backend login, using the
`passkeys:recovery` command:

**Emergency recovery from the CLI**

```bash
# List all groups and their enforcement level
vendor/bin/typo3 passkeys:recovery --list

# Disable passkey enforcement for one group (by UID)
vendor/bin/typo3 passkeys:recovery --disable-group=5

# Disable passkey enforcement for ALL groups
vendor/bin/typo3 passkeys:recovery --disable-all

# Reset the login lockout for a specific account
vendor/bin/typo3 passkeys:recovery --unlock=johndoe
```

After enforcement is disabled, affected users can log in with their password
again and re-register a passkey.

1.  The user logs in with their password (if password login is still available)
    and registers a new passkey.

> [!IMPORTANT]
> If the user's group is set to **Enforced** and the user has no remaining
> passkeys, they can still log in with a password. The **Enforced** level
> only blocks password login for users who **have** registered passkeys.
> After revoking all credentials, the user can log in with a password and
> register a replacement.

## MFA coexistence {#mfa-coexistence}

TYPO3 has built-in Multi-Factor Authentication (MFA) support since v11. The
passkey enforcement feature works alongside MFA:

-   Passkeys and MFA are independent systems. A user can have both enabled.
-   If MFA is required and passkey enforcement is active, both are evaluated.
    The MFA redirect takes precedence during login, and the passkey interstitial
    appears on subsequent requests.
-   Passkeys already provide strong authentication (possession + biometric). In
    most scenarios, requiring both MFA and passkeys is unnecessary. Consider
    accepting passkeys as a sufficient authentication factor and disabling MFA
    requirements for groups that are at the **Enforced** level.

> [!NOTE]
> The interstitial middleware exempts MFA-related routes, so users are never
> blocked from completing their MFA challenge by the passkey setup page.