First sign-in and two-step verification¶
Nebula sets twofactorauth/general/force_providers to google,nebula_passkey. Magento ships that field empty, and an empty list sends the first administrator to a screen that asks them to choose providers for the whole install before they have seen the admin. With the default Nebula ships, the administrator chooses a second factor for themselves instead.
Installing on a store that already has administrators¶
That field is the list of providers your administrators may set up, not an addition to it. An administrator already enrolled in Google Authenticator keeps that factor. An administrator enrolled in a provider that is not on the list is asked to enrol in a passkey or an authenticator app at the next sign-in. Add that provider's code to the field before you install if that is not acceptable.
The list is also cumulative, so keeping a factor is not the same as being left alone. google,nebula_passkey means the passkey is still outstanding for an administrator who has only Google Authenticator. Magento treats configuration as required while any forced provider is unactivated, so its predispatch observer redirects every admin URL to tfa/tfa/requestconfig, the page that emails a configuration link. The Nebula selection page described below is skipped in that case, because it is offered only when more than one provider is left to activate.
On a staging install with no working mail this is a dead end
The emailed link never arrives, and Force providers cannot be reached to fix it while the redirect is in force. Clear it from the command line instead.
nebulapasskey/passkey/index is not a way round it. That route is not on the two-factor allow-list, which is built from the provider's own configure, auth and extra actions, so it bounces straight back to tfa/tfa/requestconfig. nebulapasskey/tfa/configure refuses to render until the session carries the new-provider flag that the emailed token sets.
google,nebula_passkey is a config.xml default, and a default applies only where nothing is saved. A store that already has a value in that field keeps it, and nebula_passkey is not offered until you add it yourself.
Have one administrator with a working factor signed in elsewhere while you change any of this.
What an administrator sees¶
- Sign in with username and password on the Nebula login screen.
- If the account has no second factor, Nebula shows a selection page at
nebulapasskey/tfa/selectwith two options: Passkey and Authenticator app. When only one provider is left to set up, the selection page is skipped. - Passkey: the browser opens the platform prompt. Touch ID, Windows Hello, a phone, or a security key creates the credential and it is registered immediately. No email round-trip.
- Authenticator app: Magento's own flow. It emails a configuration link, and the administrator scans a QR code with the app.
- The dashboard opens. On later sign-ins the administrator is challenged for the factor they chose.
Do not seed a second factor for a person¶
bin/magento security:tfa:google:set-secret <admin username> <secret> stores a shared secret and marks the provider active in one step. That is right for an account a test suite signs in as, and wrong for a person. An account that is already active never reaches the configure screen, and the configure screen is where Magento draws the QR code, so whoever inherits the account has to type a 32-character secret into their authenticator by hand. A typo produces codes that never match, and nothing on the screen says why.
Leave the accounts people will use unconfigured, and let them enrol themselves at the first sign-in described above. If an account was seeded already, clear that provider and the next sign-in offers setup instead of a code prompt.
It takes a provider code, so google leaves a registered passkey alone. A passkey has nothing to read off a screen and nothing to type, which is why nebula_passkey is in the forced list Nebula ships by default.
Signing in with a passkey¶
Once a passkey is registered it is a way in on its own, with no username and no password. The login screen carries a Sign in with Passkey button below the username and password fields, under an or divider. The button hides itself on a browser that does not support WebAuthn.
Leave Username empty and press it, and the browser offers every passkey registered for this site, because the credential is discoverable. Type a username first and the choice is narrowed to that account. The authenticator verifies the person, and the dashboard opens.
That single step is the whole sign-in when the authenticator performed user verification and A passkey satisfies two-factor authentication is Yes. The ordinary second-factor challenge still follows when the authenticator only proved that somebody was present, and when the setting is No.
The button talks to two admin endpoints, nebulapasskey/auth/options and nebulapasskey/auth/verify. Both are unauthenticated POSTs and both are exempt from form-key validation by design, so allow them through anything fronting the admin. See Security.
A passkey can be the whole sign-in¶
With A passkey satisfies two-factor authentication set to Yes under Stores › Configuration › Security › Nebula Passkey, an administrator who signs in with a passkey that performed user verification is not asked for a second factor. The browser already verified the person and the device, and the credential is bound to this origin. Set it to No to require the second factor after every sign-in.
If you cannot get in¶
The sign-in screen carries a Forgot your password? link under the form. It opens Nebula's own Reset your password screen, which asks for the email address on the administrator account and sends a reset link. The button on that screen reads Retrieve Password.
A password reset does not clear the second factor. The factor is still required on the next sign-in. An administrator who reaches a screen their role does not permit sees a You cannot go there page whose only action is Logout.
Managing passkeys and two-step¶
- Each administrator manages their own credentials from the sidebar under System › Permissions, beside All Users and User Roles. My Passkeys holds the passkeys. 2FA holds Nebula's own authenticator app and its recovery codes. Nebula enforces that factor only where
Magento_TwoFactorAuthis not enabled. Where it is enabled, the authenticator app is Magento's own and is set up from the link it emails. - Administrators with the right ACL resource can revoke another administrator's passkeys, and a customer's passkeys or two-step, from the user and customer edit screens.
- From the command line:
bin/magento nebula:passkey:register --user=<admin username>
bin/magento nebula:passkey:reset-two-step --user=<admin username>
bin/magento security:tfa:reset <admin username> nebula_passkey
nebula:passkey:register does not enrol anything. It reports how many passkeys the user has and prints the URL to enrol at, because a passkey can only be created by the browser that will use it. security:tfa:reset is Magento's own command and takes the provider code; google resets the authenticator app.
Getting core's behaviour back¶
Clear Force providers under Stores › Configuration › Security › 2FA. The field can be restored to Nebula's default with the Use system value checkbox. If the two-factor gate is already redirecting you away from that screen, clear the field from the command line instead, as above.
Customers¶
The same module offers passkeys and two-step verification to customers on the storefront. There is no on and off setting for that half. Installing Nebula_Passkey changes the storefront at once. It overrides core's customer_form_login template and adds a Sign in with a passkey button to the login form, with its own button template for Luma and for Hyvä. It adds a security prompt card at the top of every customer account page for customers who have neither a passkey nor a confirmed two-step secret. It adds My Passkeys and Two-step verification to the account navigation.
The only storefront settings are Relying Party ID, Relying Party Name and A passkey satisfies two-step verification. What is opt-in is the customer's own enrolment, not the feature.
Turning it off means disabling the module
bin/magento module:disable Nebula_Passkey also removes the admin passkey provider and the forced-provider default that come with it. Clear any saved twofactorauth/general/force_providers value naming nebula_passkey first. Magento drops a provider code it can no longer resolve, so the passkey leaves the forced list silently, and an administrator whose only second factor was a passkey has to enrol an authenticator app through Magento's emailed link before the admin opens again. The login-form template override will also collide with a theme that overrides customer_form_login itself.
The storefront settings live in the same configuration section. See the Configuration reference.