What does it do? 

Passkeys Backend Authentication provides passwordless authentication for the TYPO3 backend using the WebAuthn/FIDO2 standard (Passkeys). Backend users can log in with a single touch or glance using biometric authenticators such as TouchID, FaceID, Windows Hello, or hardware security keys like YubiKey.

The passkey button is injected directly into the standard TYPO3 login form via a PSR-14 event listener -- no login provider switching needed. Users see the familiar login page with a Sign in with a passkey button below the Login button.

Passkeys are a modern, phishing-resistant replacement for passwords. They use public-key cryptography: the private key never leaves the user's device, and the server only stores a public key. This eliminates the risk of credential theft through phishing or database breaches.

Features 

Supported authenticators 

Any FIDO2/WebAuthn-compliant authenticator works, including:

• Apple TouchID and FaceID (macOS, iOS, iPadOS)
• Windows Hello (fingerprint, face, PIN)
• YubiKey 5 series and newer
• Android fingerprint and face unlock
• Any FIDO2-compliant hardware security key

Browser support 

WebAuthn is supported by all modern browsers:

Prerequisites 

• TYPO3 12.4 LTS, TYPO3 13.4 LTS, or TYPO3 14.x
• PHP 8.2, 8.3, 8.4, or 8.5
• HTTPS is required for WebAuthn (except for localhost during development)
• A configured TYPO3 encryption key ($GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'], minimum 32 characters)

Installation via Composer 

This is the recommended way to install the extension:

composer require netresearch/nr-passkeys-be

Activate the extension 

After installation, activate the extension in the TYPO3 backend:

1. Go to Admin Tools > Extensions
2. Search for "Passkeys Backend Authentication"
3. Click the activate button

Or use the CLI:

vendor/bin/typo3 extension:activate nr_passkeys_be

Database schema update 

The extension adds a tx_nrpasskeysbe_credential table. After activation, run the database schema update:

1. Go to Admin Tools > Maintenance > Analyze Database Structure
2. Apply the suggested changes

Or use the CLI:

vendor/bin/typo3 database:updateschema

Verify the installation 

After activation:

1. The TYPO3 backend login page should show a Sign in with a passkey button below the Login button.

   

2. In User Settings, a "Passkeys" section should appear where authenticated users can register their first passkey.

Relying Party settings 

Challenge settings 

Discoverable login 

Password login control 

Rate limiting 

Account lockout 

Cryptographic algorithms 

User verification 

Single environment 

The simplest setup: one TYPO3 instance with one domain.

Leave rpId and origin empty (the default). The extension auto-detects both values from the incoming HTTP request. Each passkey is registered against the domain it was created on.

This works for:

• A single production instance (e.g. cms.example.com)
• A local DDEV site (e.g. mysite.ddev.site)

No additional configuration is needed.

Multi-environment (local / staging / production) 

A typical setup has three environments:

• Local development: mysite.ddev.site (or mysite.local)
• Staging: staging.example.com
• Production: www.example.com

// Production and Staging: enforce passkey-only login
if (str_starts_with(
    (string)getenv('TYPO3_CONTEXT'),
    'Production'
)) {
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']
        ['nr_passkeys_be']['disablePasswordLogin']
        = '1';
}

// Development: keep password login available
// (disablePasswordLogin defaults to '0')

mysqldump \
    --ignore-table=mydb.tx_nrpasskeysbe_credential \
    mydb > dump.sql

ignore_tables:
  - tx_nrpasskeysbe_credential

Shared rpId across subdomains 

WebAuthn allows the rpId to be set to a registrable domain suffix. For example, setting rpId to example.com allows passkeys registered on staging.example.com to also work on www.example.com.

If you still need shared subdomains (e.g. staging and www), set rpId only on those environments and keep local development on auto-detect:

if (str_starts_with(
    (string)getenv('TYPO3_CONTEXT'),
    'Production'
)) {
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']
        ['nr_passkeys_be']['rpId'] = 'example.com';
    // Leave 'origin' empty -- auto-detected per
    // subdomain. Setting it explicitly would break
    // verification on other subdomains.
}
// Development: rpId stays empty
// -> auto-detect -> mysite.ddev.site

Onboarding workflow with disablePasswordLogin 

When disablePasswordLogin is enabled, the extension enforces passkey-only login per user: password login is blocked only for users who have at least one registered passkey. Users without passkeys can still log in with a password.

This enables a smooth onboarding workflow:

1. Admin creates a new backend user with a password (as usual in TYPO3).
2. User logs in with their password for the first time.
3. User registers a passkey in User Settings > Passkeys.
4. From this point on, the user must use their passkey -- password login is no longer accepted for this account.

Recovery scenarios 

If a user loses access to their authenticator:

1. An admin revokes the user's passkeys via the Admin API. Each revocation is recorded with the admin's UID and timestamp for audit purposes.
2. Once all passkeys are revoked, password login becomes available again for that user (the per-user enforcement lifts when no active credentials remain).
3. The user logs in with their password and registers a new passkey.

Containerized and multi-server deployments 

When running TYPO3 in Docker containers or behind a load balancer, the file-based cache backends lose state on container restart and are not shared across servers. This affects nonce replay protection and rate limiting.

See Multi-server cache backends for Redis configuration, and Reverse proxy and IP detection for rate limiting behind a load balancer.

Local development with DDEV 

DDEV sites (*.ddev.site) use HTTPS by default and are treated as secure contexts by browsers. Passkeys work out of the box.

ddev start
# Open https://mysite.ddev.site/typo3
# Passkeys work immediately

For http://localhost (without HTTPS), most browsers also treat this as a secure context, so passkeys will work. However, custom local domains over plain HTTP (e.g. http://mysite.local) will not work -- WebAuthn requires a secure context.

See also Troubleshooting: HTTPS requirement.

Registering a passkey 

Before you can use passwordless login, you need to register at least one passkey:

1. Log in to the TYPO3 backend with your regular password.
2. Go to User Settings (click your avatar in the top-right corner).
3. Find the Passkeys section.
4. Enter a descriptive name in the text field (e.g. "MacBook TouchID" or "Office YubiKey"). The default is "Passkey".
5. Click Add Passkey.
6. Your browser will prompt you to create a passkey using your preferred authenticator (TouchID, Windows Hello, YubiKey, etc.).
7. After successful registration the passkey appears in the list and the name input resets for the next registration.

You can register multiple passkeys for the same account -- for example, one on your laptop and one on a hardware security key.

Logging in with a passkey 

Username-first flow 

When discoverableLoginEnabled is set to false:

1. Navigate to the TYPO3 backend login page.
2. Enter your username.
3. Click Sign in with a passkey.
4. Your browser will prompt you to verify with your authenticator.
5. Upon successful verification, you are logged in.

Error handling 

If a passkey login fails (for example, the server cannot verify the assertion), a passkey-specific error message is shown on the login page:

Note

Passkeys work alongside TYPO3's built-in multi-factor authentication (MFA). If MFA is enabled, you will complete MFA verification after passkey authentication.

Managing your passkeys 

In User Settings > Passkeys, you can:

• View all your registered passkeys with their labels, creation dates, and last-used timestamps.
• Rename a passkey by clicking its label and entering a new name (max 128 characters).
• Remove a passkey you no longer need.

Fallback to password login 

By default, password login remains available. If a user does not have a passkey registered or their authenticator is unavailable, they can still log in with their regular TYPO3 password.

This fallback can be disabled with the disablePasswordLogin setting.

When passkey setup is required 

Your administrator may configure passkey enforcement for your user group. When this happens, you will see an interstitial page after logging in that prompts you to register a passkey.

The interstitial page explains the benefits of passkeys and offers two options:

• Set up now -- Takes you directly to User Settings > Passkeys where you can register a passkey (see Usage above).
• Skip for now -- Dismisses the prompt for the current session. This option is only available during the grace period.

Once the grace period expires, the Skip for now option disappears and you must register a passkey before you can access the TYPO3 backend.

If your group's enforcement level is set to Enforced, there is no grace period at all. The setup prompt appears immediately after login and cannot be skipped.

Passkey enforcement 

The extension supports per-group enforcement of passkeys with configurable grace periods. Administrators can gradually roll out passkeys from gentle encouragement to mandatory adoption. See Passkey Enforcement for the complete guide covering enforcement levels, grace periods, the admin dashboard, and recovery procedures.

Admin API endpoints 

The extension provides admin-only AJAX endpoints for credential and account management. All admin endpoints require the requesting user to have TYPO3 admin privileges. Write operations are protected by Sudo Mode (password re-verification with a 15-minute grant lifetime).

GET /typo3/ajax/passkeys/admin/list?beUserUid=<uid>

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

{"beUserUid": 123, "credentialUid": 456}

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

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

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

{"beUserUid": 123}

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

{"groupUid": 1, "enforcement": "encourage"}

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

{"beUserUid": 123}

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

{"beUserUid": 123}

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.

Configuring enforcement per group 

Enforcement is configured on each backend user group record:

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

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).
2. 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).
3. 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.
4. 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.

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:

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

Admin dashboard 

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

Monitoring adoption progress 

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

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

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.

2. The administrator opens Admin Tools > Passkey Management or uses the admin API to revoke the affected credential:

   Revoke a credential via admin API

   POST /typo3/ajax/passkeys/admin/remove
   Content-Type: application/json
   
   {"beUserUid": 123, "credentialUid": 456}

   Copied!

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

   Unlock a locked-out account

   POST /typo3/ajax/passkeys/admin/unlock
   Content-Type: application/json
   
   {"beUserUid": 123, "username": "johndoe"}

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

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.

Credential lifecycle 

Passkeys go through the following states:

1. Registered -- The credential is created via the management API and stored in the tx_nrpasskeysbe_credential table.
2. Active -- The credential is used for successful logins. The last_used_at and sign_count fields are updated on each use.
3. Revoked -- An administrator revokes the credential via the admin API. The revoked_at timestamp and revoked_by admin UID are recorded. Revoked credentials remain in the database but are rejected during authentication.
4. Deleted -- A user removes their own credential via the management API. The record is soft-deleted (deleted = 1).

Database table 

The extension uses a single table tx_nrpasskeysbe_credential with the following schema:

Monitoring 

The extension logs all significant events using the PSR-3 logging interface:

• Successful passkey registrations
• Successful passkey logins
• Failed authentication attempts (with hashed username and IP)
• Admin credential revocations
• Admin account unlocks
• Rate limit and lockout triggers

Configure TYPO3 logging writers to capture these events. Example for file logging:

$GLOBALS['TYPO3_CONF_VARS']['LOG']
    ['Netresearch']['NrPasskeysBe']
    ['writerConfiguration'] = [
        \Psr\Log\LogLevel::INFO => [
            \TYPO3\CMS\Core\Log\Writer\FileWriter::class
            => [
                'logFileInfix' => 'passkeys',
            ],
        ],
    ];

Login form injection 

The passkey button is injected into the standard TYPO3 login form via the InjectPasskeyLoginFields PSR-14 event listener. It listens to ModifyPageLayoutOnLoginProviderSelectionEvent and:

• Loads PasskeyLogin.js via PageRenderer::addJsFile()
• Injects an inline script with window.NrPasskeysBeConfig that provides loginOptionsUrl, rpId, origin, and discoverableEnabled to the JavaScript

The JavaScript builds the passkey UI (button, error area, hidden fields) dynamically via DOM manipulation and inserts it into #typo3-login-form. No Fluid partial or separate template is needed.

The passkey management panel in User Settings also uses loadJavaScriptModule() to load PasskeyManagement.js as an ES module, which imports TYPO3 native APIs (AjaxRequest, Notification, Modal, sudoModeInterceptor, DocumentService).

Banner injection 

The InjectPasskeyBanner PSR-14 event listener listens to AfterBackendPageRenderEvent and loads PasskeyBanner.js on every backend page. The JavaScript fetches enforcement status via AJAX, checks sessionStorage for prior dismissal, and renders a rich banner with title, passkey explanation, documentation link, and administrator contact help text. The banner supports TYPO3 v12/v13 (via .scaffold-content-module) and v14 (via typo3-backend-module-router parent fallback).

Interstitial middleware 

PasskeySetupInterstitial is a PSR-15 middleware that intercepts backend requests for users whose effective enforcement level is Required or Enforced. If the user has no registered passkeys, it renders a full-page interstitial prompting them to register.

The middleware exempts login, logout, AJAX, MFA, and passkey API routes. During the grace period the user can skip the interstitial (protected by a CSRF nonce). Once the grace period expires or the level is Enforced, skipping is disabled.

Authentication data flow 

The passkey assertion and challenge token are packed into the userident field as JSON:

{
    "_type": "passkey",
    "assertion": {
        "id": "...",
        "type": "public-key",
        "response": {}
    },
    "challengeToken": "..."
}

The PasskeyAuthenticationService reads from $this->login['uident'], detects the _type: "passkey" marker, and extracts the assertion and challenge token for verification.

Authentication service 

PasskeyAuthenticationService extends TYPO3's AbstractAuthenticationService and is registered at priority 80 (higher than SaltedPasswordService at 50).

The service implements two methods:

• getUser() -- Checks if the login data contains a passkey payload (JSON with _type: "passkey"). If it does, the user is looked up by username. If no passkey data is present, the request falls through to the next auth service.

• authUser() -- Returns:

  • 200 -- Authenticated, stop chain (passkey verified)
  • 100 -- Not responsible (no passkey data, let next service handle it)
  • 0 -- Authentication failed

Because TYPO3 authentication services are instantiated by the service manager (not the DI container), dependencies are obtained via GeneralUtility::makeInstance().

Public route middleware 

PublicRouteResolver is a PSR-15 middleware that allows passkey login API endpoints (/typo3/passkeys/login/*) to be accessed without an authenticated backend session. Without it, TYPO3 would redirect unauthenticated requests to the login page.

Domain model 

The Credential class is a plain PHP value object (not Extbase) with fromArray()/toArray() for database serialization.

Key fields:

• credentialId -- WebAuthn credential identifier (binary)
• publicKeyCose -- COSE-encoded public key (binary blob)
• signCount -- Counter incremented on each use (clone detection)
• userHandle -- SHA-256 hash of the user UID + encryption key
• aaguid -- Authenticator Attestation GUID
• transports -- JSON array of transport hints

Controllers 

The extension registers backend routes for three controller groups. All controllers use the JsonBodyTrait for parsing JSON request bodies. Login routes use Routes.php (public access). Management and admin routes use AjaxRoutes.php (AJAX, with Sudo Mode on write operations). All paths below are relative to /typo3/.

Routes marked with * are protected by TYPO3's Sudo Mode. When accessed without a recent password verification, they return HTTP 422 with sudoModeInitialization data. The JavaScript handles this transparently by showing a password dialog and retrying the request.

Service classes 

JavaScript modules 

• PasskeyLogin.js -- Login form passkey button and WebAuthn flow
• PasskeyManagement.js -- User Settings passkey management panel
• PasskeyBanner.js -- Encourage-stage onboarding banner
• PasskeyDashboard.js -- Admin dashboard enforcement controls
• PasskeyAdminInfo.js -- Admin passkey info in user records

Running tests 

# Unit tests
composer ci:test:php:unit

# Fuzz tests
composer ci:test:php:fuzz

# Functional tests (requires MySQL)
composer ci:test:php:functional

# Static analysis (PHPStan level 10)
composer ci:test:php:phpstan

# Code style (PER-CS3.0)
composer ci:test:php:cgl

# Mutation testing (Infection, min-MSI 80%, covered-MSI 80%)
composer ci:mutation

# JavaScript unit tests (Vitest)
npx vitest run

# E2E tests (Playwright, PHP built-in server + MySQL)
# Set TYPO3_BASE_URL to override the default http://localhost:8080
Build/Scripts/runTests.sh e2e

WebAuthn security model 

WebAuthn (Web Authentication) is a W3C standard that uses public-key cryptography for authentication:

• During registration, the authenticator generates a key pair. The private key stays on the device; the public key is sent to the server.
• During authentication, the server sends a random challenge. The authenticator signs it with the private key. The server verifies the signature with the stored public key.

This provides inherent protection against:

• Phishing -- The credential is bound to the origin (domain). It cannot be used on a different domain, even if the user is tricked into visiting one.
• Credential theft -- The private key never leaves the authenticator device. Even if the server database is compromised, attackers cannot impersonate users.
• Replay attacks -- Each authentication uses a unique challenge, and the signature counter detects cloned authenticators.

HMAC-signed challenge tokens 

Challenge tokens are the core mechanism preventing unauthorized authentication attempts. Each token contains:

1. A 32-byte random challenge generated by random_bytes(32)
2. An expiration timestamp (configurable TTL, default 120 seconds)
3. A single-use nonce (32 hex characters from random_bytes(16))

These components are concatenated and signed with HMAC-SHA256 using the TYPO3 encryption key as the signing secret. The final token is base64-encoded.

Security properties:

• Integrity -- The HMAC ensures the token cannot be tampered with. Verification uses hash_equals() for constant-time comparison, preventing timing side-channel attacks.
• Freshness -- The expiration timestamp prevents use of stale tokens.
• Single-use -- The nonce is stored in a TYPO3 cache and consumed on first use. Subsequent uses of the same token are rejected.
• Signing key requirements -- The TYPO3 encryption key must be at least 32 characters. The extension throws a clear error if this requirement is not met.

Nonce replay protection 

Each challenge token contains a nonce that is stored in a TYPO3 cache (SimpleFileBackend) upon creation. During verification:

1. The nonce is looked up in the cache.
2. If found, it is immediately invalidated (removed from cache).
3. If not found (already used or expired), the verification fails.

This ensures each challenge token can only be used exactly once, even if an attacker intercepts and replays it.

The nonce cache has a TTL slightly longer than the challenge TTL (extra 60 seconds buffer) to handle clock skew.

Rate limiting 

User enumeration prevention 

The login endpoints return identical error responses regardless of whether a username exists. Additionally, requests for non-existent users include a randomized delay (50--150ms via usleep(random_int(50000, 150000))) to normalize response timing and prevent timing-based enumeration.

The authentication service logs only hashed usernames (hash('sha256', $username)) for unknown user attempts.

Credential ownership verification 

Before any credential mutation (rename, remove), the extension verifies that the credential belongs to the requesting user. This prevents unauthorized users from modifying other users' credentials, even if they know the credential UID.

Admin operations verify admin status via BackendUserAuthentication::isAdmin() and record the admin's UID in audit trails.

Last credential protection 

When disablePasswordLogin is enabled, users cannot remove their last remaining passkey. This prevents users from accidentally locking themselves out of the system when password login is disabled.

Signature counter validation 

The WebAuthn signature counter (sign_count) is updated after each successful authentication. The web-auth/webauthn-lib validates that the counter is strictly increasing, which helps detect cloned authenticators.

Soft delete and revocation 

The extension supports two credential removal mechanisms:

• Soft delete (user-initiated): Sets deleted = 1. The credential record is preserved in the database but excluded from all queries.
• Revocation (admin-initiated): Sets revoked_at and revoked_by without setting the delete flag. Revoked credentials are explicitly checked and rejected during authentication, providing a clear audit trail of who revoked the credential and when.

Label sanitization 

User-provided passkey labels are sanitized:

• Trimmed of leading/trailing whitespace
• Truncated to 128 characters maximum (mb_substr)
• Empty labels default to "Passkey"

Trusted hosts pattern 

When rpId and origin are left empty (the default), the extension auto-detects them from the HTTP_HOST server variable. An attacker who can inject an arbitrary Host header could cause the extension to generate challenge tokens bound to a malicious origin.

TYPO3 mitigates this with the trustedHostsPattern setting, but the default value .* allows any host header.

$GLOBALS['TYPO3_CONF_VARS']['SYS']['trustedHostsPattern']
    = '(^|\.)example\.com$';

Alternatively, set rpId and origin explicitly in the extension configuration. This bypasses auto-detection entirely and removes the dependency on host header validation for passkey operations.

Reverse proxy and IP detection 

Rate limiting and account lockout use the client's IP address (via GeneralUtility::getIndpEnv('REMOTE_ADDR')). Behind a reverse proxy, all requests appear to originate from the proxy's IP address unless TYPO3 is configured to read the real client IP from forwarded headers.

Without this configuration:

• Rate limiting becomes ineffective -- all clients share a single counter and hit the limit collectively.
• Account lockout affects all users -- one locked account blocks authentication for every user behind the same proxy.

Configure TYPO3 to trust your reverse proxy:

// IP address(es) of your reverse proxy (comma-separated)
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP']
    = '10.0.0.1,10.0.0.2';

// Use the last (rightmost) value in X-Forwarded-For
$GLOBALS['TYPO3_CONF_VARS']['SYS']
    ['reverseProxyHeaderMultiValue'] = 'last';

Multi-server cache backends 

The extension uses two TYPO3 caches:

• nr_passkeys_be_nonce -- Stores single-use nonces for challenge replay protection (default backend: SimpleFileBackend).
• nr_passkeys_be_ratelimit -- Stores rate-limit counters and lockout flags (default backend: FileBackend).

File-based cache backends store data on the local filesystem. In a multi-server deployment (multiple TYPO3 instances behind a load balancer), each server maintains its own independent cache. This has two consequences:

1. Nonce replay across servers -- A challenge token consumed on server A still exists in server B's cache, allowing a replayed token to pass verification on server B.
2. Rate-limit bypass -- An attacker can distribute requests across servers, with each server tracking only a fraction of the total attempts.

For multi-server deployments, configure a shared cache backend:

// Use Redis for nonce cache
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']
    ['cacheConfigurations']['nr_passkeys_be_nonce']
    ['backend']
    = \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']
    ['cacheConfigurations']['nr_passkeys_be_nonce']
    ['options'] = [
        'database' => 3,
        'defaultLifetime' => 300,
        // 'hostname' => '127.0.0.1',
        // 'port' => 6379,
        // 'password' => '',
    ];

// Use Redis for rate-limit cache
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']
    ['cacheConfigurations']['nr_passkeys_be_ratelimit']
    ['backend']
    = \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']
    ['cacheConfigurations']['nr_passkeys_be_ratelimit']
    ['options'] = [
        'database' => 4,
        'defaultLifetime' => 600,
        // 'hostname' => '127.0.0.1',
        // 'port' => 6379,
        // 'password' => '',
    ];

"Failed to generate options" / encryptionKey too short 

Symptoms

• The passkey settings panel shows: "Passkey management is unavailable. The TYPO3 encryption key is missing or too short."
• The management API returns HTTP 500 with `Failed to generate options: TYPO3 encryptionKey is missing or too short (min 32 chars).`

Error codes

• 1700000040 (WebAuthnService)
• 1700000050 (ChallengeService)

Cause

Both HMAC-signed challenge tokens and the WebAuthn credential serialization depend on $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey']. This key must be at least 32 characters long. Fresh TYPO3 installations that skipped the Install Tool wizard may have an empty or very short key.

Fix

1. Open Admin Tools > Settings > Configure Installation-Wide Options.
2. Set [SYS][encryptionKey] to a random string of at least 64 characters. The Install Tool offers a "Generate" button for this.

3. Alternatively, set it in config/system/settings.php:

   config/system/settings.php

   return [
       'SYS' => [
           'encryptionKey' => 'your-random-string...',
       ],
   ];

   Copied!

"Passkeys require a secure connection (HTTPS)" 

Symptoms

The login page shows "Passkeys require a secure connection (HTTPS)." and the passkey button is disabled.

Cause

The WebAuthn specification requires a secure context. Browsers block navigator.credentials.create() and navigator.credentials.get() on plain HTTP origins.

Fix

• Use HTTPS for your TYPO3 backend. In local development https://localhost or https://*.ddev.site satisfies the requirement.
• http://localhost is also treated as a secure context by most browsers, but other HTTP origins are not.

Extension log location 

The extension logs passkey events (registration, authentication, errors) via the PSR-3 LoggerInterface. With the default TYPO3 logging configuration, messages are written to:

var/log/typo3_<hash>.log

If you have configured a custom log file via $GLOBALS['TYPO3_CONF_VARS']['LOG'], check the path set for the Netresearch\NrPasskeysBe namespace.

Example custom configuration:

$GLOBALS['TYPO3_CONF_VARS']['LOG']
    ['Netresearch']['NrPasskeysBe']
    ['writerConfiguration'] = [
        \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [
            \TYPO3\CMS\Core\Log\Writer\FileWriter::class
            => [
                'logFile' =>
                    \TYPO3\CMS\Core\Core\Environment
                        ::getVarPath()
                    . '/log/passkey_auth.log',
            ],
        ],
    ];

Enabling debug mode 

To see full stack traces in error responses (development only):

1. Open Admin Tools > Settings > Configure Installation-Wide Options.
2. Set [SYS][displayErrors] to 1.
3. Set [SYS][devIPmask] to your IP address or *.

0.8.2 

0.8.1 

0.8.0 

0.7.0 

0.6.0 

0.5.0 

0.4.0 

0.3.0 

0.2.0 

0.1.0 

Initial release.