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 for convenience
// (disablePasswordLogin defaults to '0', no override needed)

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 -- it is auto-detected per subdomain.
    // Setting it explicitly would break verification on other subdomains.
}
// Development: rpId stays empty -> auto-detect -> mysite.ddev.site

User onboarding 

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:

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.

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"}

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',
        ],
    ],
];

Architecture overview 

The extension consists of these core components:

Classes/
  Authentication/     Auth service (TYPO3 auth chain)
  Configuration/      Extension configuration value object
  Controller/         REST API controllers (Login, Manage, Admin)
  Domain/Model/       Credential entity
  EventListener/      PSR-14 listener (login form injection)
  Middleware/          PSR-15 middleware (public route resolver)
  Service/            Business logic services

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

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.

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

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 

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

Running tests 

# Unit tests (301 tests, 1060 assertions)
composer ci:test:php:unit

# Fuzz tests (122 tests, 1608 assertions)
composer ci:test:php:fuzz

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

# Static analysis (PHPStan level 10)
composer ci:stan

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

# JavaScript unit tests (33 tests, Vitest)
npm run test:js

# Mutation testing (Infection, MSI >= 80%)
composer ci:mutation

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"

Production deployment requirements 

The extension's security mechanisms depend on certain TYPO3 and server configurations being set correctly. Review each section below before deploying to production.

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

// 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';

// Use Redis for nonce cache (requires typo3/cms-core Redis backend)
$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:

   return [
       'SYS' => [
           'encryptionKey' => 'your-random-string-at-least-64-chars...',
       ],
   ];

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

0.4.0 

0.3.0 

0.2.0 

0.1.0 

Initial release.