Download the PHP package mage-os/module-passkey-auth without Composer

MageOS Passkey Authentication

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. There is no password to remember, phish, or leak.

Built on web-auth/webauthn-lib 5.2 or later.

Documentation: see the manual for setup, customer and admin guides, the headless API, and troubleshooting. Changes between releases are in CHANGELOG.md.

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
• 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 signs the customer out everywhere and notifies them)
• 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

Customer passkeys are disabled by default on new installs. Upgrades from a pre-1.0 release that already has customer passkeys keep them on. Turn them on under Enable Passkey Authentication (see below), or run:

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. There is nothing to configure.

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

Passkeys come back as {id, name, transports, created_at, last_used_at}, the same fields as GraphQL. See Headless API.

GraphQL API

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

Events

entity_id is the row ID, credential_id the WebAuthn credential ID, and reason a fixed code (credential_not_found or verification_failed). Names and codes are constants on Model\PasskeyEvents. See the Developer guide.

A passkey sign-in also fires core customer_login, on the storefront and over REST, SOAP, and GraphQL.

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:

Overriding Services

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

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): 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): configure dev/tests/api-functional/phpunit_graphql.xml for your instance, then from dev/tests/api-functional run ../../../vendor/bin/phpunit -c phpunit_graphql.xml ../../../vendor/mage-os/module-passkey-auth/Test/Api/GraphQl. The default suite doesn't include module tests, so give the path.

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 claimed atomically on verification and cannot be reused.
• Rate limiting: Options generation (10 requests/60s per email and IP, or per customer for registration) and failed sign-ins (5 per 15 minutes per IP, shared by the storefront, REST, and GraphQL) are rate-limited. Behind a proxy, Magento must see the real client IP. See How it works and security.
• Sign-count validation: Rejects sign-ins whose signature counter doesn't increase, a sign of a cloned authenticator.
• 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.
• Per-website accounts: With customer accounts shared per website, a passkey only signs in on its own customer's website.
• Account checks: Like password sign-in, passkey sign-in refuses locked accounts, accounts awaiting email confirmation, and customer groups excluded from the website. Failed passkey attempts never lock an account.
• Sign-out on removal: An admin revoke ends the customer's storefront sessions and revokes their API tokens. A customer deleting a passkey ends their other storefront sessions, as a password change does.
• Login as Customer: Passkey registration is refused while an admin is signed in as the customer on the storefront. Known limitation: REST and GraphQL registration with a token from generateCustomerTokenAsAdmin is not blocked.

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