Passkey Enforcement

New in version 0.6.0

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

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

Enforcement is configured on each backend user group record:

Go to System > Backend Users and select the Backend User Groups list.
Edit a group record.
Switch to the Passkeys tab.
Set the Passkey Enforcement dropdown to the desired level.
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

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

An administrator sets a group to Required with a grace period (e.g. 14 days).
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).
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.
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

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

Strictest level wins. If a user belongs to group A (Encourage) and group B (Required), the effective level is Required.
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.

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

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

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

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

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

Navigate to Admin Tools > Passkey Management.
The progress bar at the top shows overall adoption (e.g. "12 of 25 users have passkeys -- 48%").
Review the per-group table to identify groups with low adoption.
Use the Send reminder action for individual users who have not yet registered.
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

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

The user contacts an administrator.
The administrator opens Admin Tools > Passkey Management or uses the admin API to revoke the affected credential:
```
POST /typo3/ajax/passkeys/admin/remove
Content-Type: application/json

{"beUserUid": 123, "credentialUid": 456}
```
Copied!

If the user is locked out, the administrator can unlock the account:

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

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

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

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.