Extend the Neos backend login to support second factors. We support TOTP tokens (Authenticator apps) and WebAuthn / FIDO2 hardware security keys (e.g. Yubikey).
Screen.Recording.2022-02-08.at.17.07.59.mov
This package allows all users to register their personal second factor — either a TOTP token (Authenticator App) or a hardware security key (Yubikey / WebAuthn). Users can register one of each and pick which to use at login. As an Administrator you are able to delete factors for users again, in case they locked themselves out.
Browsers expose WebAuthn only over https:// or on localhost. Make sure the Neos backend is served
over HTTPS in production, otherwise the security-key flow will fail.
Configure the relying party identifier when your backend hostname differs from the registered domain:
Sandstorm:
NeosTwoFactorAuthentication:
webAuthn:
relyingPartyName: 'My CMS'
# null means: derive from the request hostname (works for same-origin deployments).
# Set to the registrable domain ('example.com') if you serve the backend from a subdomain
# and want credentials to be usable across subdomains.
relyingPartyId: null
# Default is 'discouraged' so FIDO U2F-only authenticators (e.g. YubiKey 4) work
# via the browser's U2F-compat fallback. Set to 'preferred' or 'required' to
# demand PIN/biometric — note that 'required' excludes U2F-only keys.
userVerification: 'discouraged'
timeout: 60000There is no setting for attestation. We always request the none conveyance preference, so the
browser does not return identifying attestation data about the authenticator. Only the none and
fido-u2f attestation statement formats are accepted when loading a credential (the latter is
required for U2F-only authenticators registered via the browser's U2F-compat fallback). Other
attestation statement types are not supported yet.
| Authenticator | userVerification: discouraged |
userVerification: required |
|---|---|---|
| YubiKey 5 / FIDO2 keys | ✅ touch | ✅ PIN + touch |
| YubiKey 4 / older U2F-only keys | ✅ touch (U2F-compat) | ❌ not supported |
| Platform authenticators (Touch ID, Windows Hello) | ✅ biometric | ✅ biometric |
| Package Version | Neos / Flow Version | Released? | Supported | Remarks |
|---|---|---|---|---|
| 2.x | 9.x, 8.x, 7.x | ✅ | ✅ | main branch |
| 1.x | 9.x, 8.x, 7.x, 3.x | ✅ |
To enforce the setup and usage of 2FA you can add the following to your Settings.yaml.
Sandstorm:
NeosTwoFactorAuthentication:
# enforce 2FA for all users
enforceTwoFactorAuthentication: trueWith this setting, no user can login into the CMS without setting up a second factor first.
In addition, you can enforce 2FA for specific authentication providers and/or roles by adding following to your Settings.yaml
Sandstorm:
NeosTwoFactorAuthentication:
# enforce 2FA for specific authentication providers
enforce2FAForAuthenticationProviders: ["Neos.Neos:Backend"]
# enforce 2FA for specific roles
enforce2FAForRoles: ["Neos.Neos:Administrator"]To override the default sitename as issuer label, you can define one via the configuration settings:
Sandstorm:
NeosTwoFactorAuthentication:
# (optional) if set this will be used as a naming convention for the TOTP. If empty the Site name will be used
issuerName: ""Thx to @Sebobo @Benjamin-K for creating a list of supported and testet apps!
iOS:
- Google Authenticator (used for development) ✅
- Authy ✅
- Microsoft Authenticator ✅
- 1Password ✅
Android:
- Google Authenticator ✅
- Microsoft Authenticator ✅
- Authy ✅
- We introduced a new middleware
SecondFactorMiddlewarewhich handles 2FA on a NeosSessionbasis.-
This is an overview of the checks the
SecondFactorMiddlewaredoes for any request:┌─────────────────────────────┐ │ Request │ └─────────────────────────────┘ ▼ ... middleware chain ... ▼ ┌───────────────────────────────┐ │ SecurityEntryPointMiddleware │ └───────────────────────────────┘ ▼ ┌───────────────────────────────────────────────────────────────────┐ │ SecondFactorMiddleware │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 1. Skip, if no authentication tokens are present, because │ │ │ │ we're not on a secured route. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 2. Skip, if 'Neos.Backend:Backend' authentication token not │ │ │ │ present, because we only support second factors for Neos │ │ │ │ backend. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 3. Skip, if 'Neos.Backend:Backend' authentication token is │ │ │ │ not authenticated, because we need to be authenticated │ │ │ │ with the authentication provider of │ │ │ │ 'Neos.Backend:Backend' first. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 4. Skip, if second factor is not set up for account and not │ │ │ │ enforced via settings. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 5. Skip, if second factor is already authenticated. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 6. Redirect to 2FA login, if second factor is set up for │ │ │ │ account but not authenticated. │ │ │ │ Skip, if already on 2FA login route. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 7. Redirect to 2FA setup, if second factor is not set up for│ │ │ │ account but is enforced by system. │ │ │ │ Skip, if already on 2FA setup route. │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ X. Throw an error, because any check before should have │ │ │ │ succeeded. │ │ │ └─────────────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────┘ ▼ ... middlewares ...
-
- the login screen for the second factor is a hard copy of the login screen from the
Neos.Neospackage- just replaced the username/password form with the form for the second factor
- maybe has to be replaced when neos gets updated
- hopefully the rest of this package is solid enough to survive the next mayor Neos versions ;)
This actually has been the approach up until version 1.0.5.
One issue with this is the fact, that we want the user to be logged in with that token via the
PersistedUsernamePasswordProvider, but at the same time to not be logged in with that token as long as 2FA is
not authenticated as well.
We found it hard to find a secure way to model the 2FA setup solution when 2FA is enforced, but the user does not have a
second factor enabled, yet.
The middleware approach makes a clear distinction between "Logging in" and "Second Factor Authentication", while still being session based and unable to bypass.
The AuthenticationProviderManager requires to authorize all tokens at the same time otherwise, it will throw an Exception (see AuthenticationProviderManager Line 181
if ($this->authenticationStrategy === Context::AUTHENTICATE_ALL_TOKENS) {
throw new AuthenticationRequiredException('Could not authenticate all tokens, but authenticationStrategy was set to "all".', 1222203912);
})
This leads to an error where the AuthenticationProviderManager throws exceptions before the user is able to enter any
credentials. The SecurityEntryPointMiddleware catches those exceptions and redirects to the Neos Backend Login, which
causes the same exception again. We get caught in an endless redirect.
The Neos Flow Security Documentation
suggests how to implement a multi-factor-authentication, but this method seems like it was never tested. At the moment of writing
it seems like the authenticationStrategy: allTokens flag is broken and not usable.
The package ships with end-to-end tests built on Playwright and written in Gherkin syntax via playwright-bdd.
Tests require Docker and Node.js. All Makefile targets are run from Tests/E2E/. Run the initial setup once — it builds the SUT images and installs the test dependencies (if nvm is available it will automatically switch to the Node version from .nvmrc):
make setup # build SUT images + install test dependencies
make setup-test # only install node dependencies, playwright and generate BDD filesRe-generate Playwright spec files whenever a .feature file changes:
make generate-bdd-filesRun the tests:
make test # run all tests (neos8 + neos9, all configurations)
make test-neos8 # run all neos8 tests
make test-neos8-defaults # default configuration only
make test-neos8-enforce-all # enforceTwoFactorAuthentication: true
make test-neos8-enforce-role
make test-neos8-enforce-provider
make test-neos9 # same targets for neos9 / PHP 8.5
make sut-prune # tear down all docker compose environments and remove volumesRun make help to see all available targets.
To debug a test, run the test from Tests/E2E/ with flags like this:
npm run test:neos8:enforce-all -- --debug- to run the test in headed mode with Playwright Inspectornpm run test:neos8:enforce-all -- --ui- to run the test in headed mode with Playwright Test Runner UI
If you just want to see the test running in the browser just npm run test:neos8:enforce-all -- --headed.
While debugging you can also enter the SUT with
make enter-sut-neos8andmake enter-sut-neos9respectively.You can even the tests you want to debug with
npm run test:neos8:enforce-all -- --grep @debugand adding the@debugtag to the scenario you want to debug. But using the --ui flag is usually more convenient for debugging.
There are two docker compose environments in Tests/system_under_test/:
neos8/— Neos with PHP 8.2neos9/— Neos with PHP 8.5
Both are built from the repository root as the Docker build context, so the local package source is copied into the container and installed via a Composer path repository. This means every test run tests the current working tree of the package, not a published version.
The FLOW_CONTEXT environment variable is passed into the docker compose environment via variable substitution, and Flow's hierarchical configuration loading picks up the corresponding Settings.yaml from the SUT:
| Playwright tag | FLOW_CONTEXT |
What is tested |
|---|---|---|
@default-context |
Production/E2E-SUT |
No enforcement — 2FA is optional |
@enforce-for-all |
Production/E2E-SUT/EnforceForAll |
enforceTwoFactorAuthentication: true |
@enforce-for-role |
Production/E2E-SUT/EnforceForRole |
Enforcement scoped to Neos.Neos:Administrator |
@enforce-for-provider |
Production/E2E-SUT/EnforceForProvider |
Enforcement scoped to an authentication provider |
Each scenario starts with a clean state. An AfterScenario hook runs after every scenario to:
- Log the browser out via a POST to
/neos/logout - Delete all Neos users (
./flow user:delete --assume-yes '*')
Deleting all users also cascades to their 2FA devices, so no separate cleanup step is needed. Users and devices are re-created by the Background steps at the start of each scenario.
Gherkin / BDD over plain Playwright specs — the feature files document the intended behaviour of each configuration variant at a level that is readable without knowing the implementation. The generated Playwright spec files (.features-gen/) are not committed; they are re-generated by bddgen before each test run.
UI-only device enrolment — 2FA devices are enrolled through the browser UI (the backend module or the setup page) rather than a dedicated CLI command. This avoids coupling the tests to internal persistence details and exercises the same enrolment path a real user would take. The deviceNameSecretMap in helpers/state.ts carries TOTP secrets across steps within a scenario (e.g. from the enrolment step to the OTP entry step).
Sequential execution — tests run with workers: 1 and fullyParallel: false because all scenarios share a single running SUT container and a single database. Running them in parallel would cause interference between scenarios.
User creation via docker exec — Neos user creation is done through the Flow CLI (./flow user:create) rather than the UI because the UI path is not part of what this package tests, and using the CLI is faster and more reliable for setup.