README

Passwordless login for Magento 2 customer accounts using the WebAuthn/FIDO2 standard. Customers register passkeys (biometric, security key, or device PIN) and sign in with a single tap — no passwords to remember, phish, or leak.

Built on web-auth/webauthn-lib v5.

Key Features

Passwordless Authentication

• One-tap login: Customers authenticate with fingerprint, Face ID, Windows Hello, or a hardware security key
• Passkey autofill (conditional UI): Saved passkeys appear directly in the browser's email-field autofill dropdown on the login page and at checkout — no extra button to discover
• Token-based sessions: Successful passkey authentication issues a standard Magento customer token
• Anti-enumeration: Sign-in options for an email with no passkeys (or no account) carry a stable decoy credential, so they look like those of an account with a passkey

Credential Management

• My Account page: Customers add, rename, and delete passkeys from their account dashboard
• Security notification emails: Customers are emailed when a passkey is added to or removed from their account
• Clone detection: Sign-count tracking detects copied authenticators

Theme & API Coverage

• Luma and Hyvä: Native storefront implementations for both (RequireJS widgets and Alpine.js components sharing one ceremony core)
• REST and GraphQL: Full registration, authentication, and management surface for headless storefronts

Store Admin Controls

• Customer Passkeys grid: View and revoke any customer's passkeys under Customers > Customer Passkeys (revocation notifies the customer)
• Admin passkey TFA: Passkey provider for the Magento admin two-factor framework, including a security:tfa:passkey:reset-all CLI command
• Enrollment prompts: Optional banners on account pages after password login or account creation, with built-in dismissal cooldown to avoid nagging
• Rate limiting: Built-in cache-based limits on options requests and verification failures

Screenshots

The storefront screenshots show the Luma theme.

Sign in with a passkey	Enrollment prompt after password sign-in

My Account › Passkeys: add, rename and delete passkeys.

On a phone	Security notification email

Admin: the Customers › Customer Passkeys grid (single and mass revoke), and registering an admin passkey for two-factor authentication.

Requirements

Installation

composer require mage-os/module-passkey-auth
bin/magento setup:upgrade

Customer passkeys are disabled by default. Turn them on under Enable Passkey Authentication (see below), or run:

bin/magento config:set customer/passkey/enabled 1

The admin passkey 2FA provider doesn't depend on this setting; it's managed with the other 2FA providers.

Configuration

Navigate to Stores > Configuration > Customers > Customer Configuration > Passkey Authentication.

The Relying Party (RP) ID and allowed origins are derived automatically from the store's base URL — no manual configuration required.

WebAuthn parameters (user verification, attestation conveyance, ceremony timeout, authenticator attachment, and max credentials per customer) use sane defaults internally and are not exposed as admin settings.

Architecture

Service Contracts

All business logic is exposed through Api interfaces:

REST API

GraphQL API

The schema mirrors the REST surface; WebAuthn ceremony options travel as JSON strings (options_json) ready for navigator.credentials.create()/get():

# Guest: start + finish sign-in (returns a customer bearer token)
mutation { createPasskeyAuthenticationOptions(email: "jane@example.com") { options_json } }
mutation {
    verifyPasskeyAuthentication(input: {
        challenge_token: "…", assertion_response: "…"
    }) { customer_token }
}

# Customer (Authorization: Bearer <token>): register + manage
mutation { createPasskeyRegistrationOptions { options_json } }
mutation {
    verifyPasskeyRegistration(input: {
        challenge_token: "…", attestation_response: "…", name: "Chrome on Windows"
    }) { id name }
}
query { customerPasskeys { id name transports created_at last_used_at } }
mutation { renameCustomerPasskey(passkeyId: 1, name: "Work laptop") { id name } }
mutation { deleteCustomerPasskey(passkeyId: 1) { success } }

Events

The bundled notification emails are implemented as observers on the register/remove events, so they fire for every entry point (storefront, REST, GraphQL, admin revocation).

Database

passkey_credential — Stores registered WebAuthn credentials. One customer can have multiple credentials (up to 10). Foreign key to customer_entity with CASCADE delete.

passkey_challenge — Temporary single-use challenges with a 5-minute TTL. Cleaned up by the passkey_challenge_cleanup cron job.

Extensibility

Observing Passkey Events

Create an observer in your module's etc/events.xml:

<event name="passkey_authentication_success">
    <observer name="my_module_passkey_login" instance="Vendor\Module\Observer\PasskeyLogin"/>
</event>

Overriding Services

All service contracts can be replaced via DI preferences in etc/di.xml:

<preference for="MageOS\PasskeyAuth\Api\AuthenticationVerifierInterface"
            type="Vendor\Module\Model\CustomVerifier"/>

Frontend Customization

The module provides three jQuery UI widgets that can be extended via RequireJS mixins:

• passkeyLogin — Login page authentication flow
• passkeyManage — My Account credential management (add/rename/delete)
• enrollmentPrompt — Enrollment banner after password login

Templates are in view/frontend/templates/ and can be overridden via theme fallback. Styles use Luma/blank theme variables and patterns (.message.info, .data.table, .action.primary) for native theme consistency.

Testing

• Unit tests (standalone, run in CI): composer install && composer test
• Integration tests (Test/Integration, Magento integration conventions — @magentoDataFixture, @magentoConfigFixture, @magentoDbIsolation): install the module into a Magento instance, then from dev/tests/integration run ../../../vendor/bin/phpunit ../../../vendor/mage-os/module-passkey-auth/Test/Integration
• GraphQL api-functional tests (Test/Api/GraphQl): run from dev/tests/api-functional with a configured GraphQL endpoint

Security

• HTTPS required: WebAuthn ceremonies are rejected by browsers on non-secure origins. The module detects non-secure contexts and displays a specific error message.
• Change notifications: Customers are emailed whenever a passkey is added or removed, so silent credential planting is visible. See SECURITY.md for the disclosure policy.
• Single-use challenges: Each challenge token is consumed on verification and cannot be reused.
• Rate limiting: Options generation (10 requests/60s) and verification failures (5 failures/900s) are rate-limited per customer.
• Sign-count validation: Detects cloned authenticators by tracking the signature counter.
• Anti-enumeration: Authentication options for an email with no passkeys (or no account) carry a stable, secret-derived decoy credential descriptor instead of an empty list.
• Ownership enforcement: All credential operations validate that the credential belongs to the requesting customer.

Contributing

Issues and pull requests welcome on GitHub.

License

This module is licensed under the Open Software License 3.0.

Support

• Issues: GitHub Issues
• Community: Mage-OS Discord