Documentation
TYPO3 Module “Single-Sign-On”
Version 2.0.3 (04 Nov 2026)
Chapters of this Documentation
Backend SSO is switched on by enableBE together with a BackendServiceProviderConfigurationFile. With enableBE on and no file, the extension registers nothing usable and the login screen looks exactly as it did—the most common reason backend SSO "does not work" is that the file is missing or its path does not resolve.
The Provider Switch
With SSO configured, the login screen gains an entry in TYPO3’s own login provider list: label Login with SSO, sorting 40, so it sits below the username/password provider that stays primary. Clicking it appends ?loginProvider=1433416748 and dispatches straight to the identity provider.
The extension does not style that button or ship a template for it. The core Login layout renders the switch from the registration, so it looks like every other provider entry.
Coming back from the identity provider posts the assertion to the assertion consumer service route, and the same request renders the backend—see A Backend Login.
The Stale Provider Cookie
TYPO3 remembers the last provider used in a be_lastLoginProvider cookie and resolves it before the provider is asked to render anything. That means a browser that once logged in via SSO arrives claiming SSO even on a request where SSO must not be used—for example after following a password reset link.
The provider detects this and re-resolves as if the primary provider had been selected: the password form is rendered, and the "forgot password" link and the form action are rebuilt with the primary provider's identifier. Without that, completing a password reset would bounce back to the identity provider, and a successful password login would keep rewriting the cookie back to SSO on every visit instead of correcting itself once.
If the primary provider is not the username/password one—another extension registered a provider with a lower sorting—the request is redirected to it explicitly, so that provider renders its own form rather than having its identifier attached to somebody else's markup.
Enforcing SSO
enforceSSO: true as a top-level key in the backend configuration file makes SSO the only accepted backend login:
enforceSSO: true
idp: '%env(SSO_METADATAURL)%'Two things happen, and the second is the one that matters:
The username/password provider is removed from the login screen for that request, leaving SSO as the only entry—and with no form left to fall back to, the login screen dispatches to the identity provider immediately rather than showing a switch with one option.
A posted password is rejected during authentication. The authentication service runs at priority 80, above the username/password service at 50, and aborts the whole chain when it sees a login without SSO claims while enforcement is on. So posting credentials directly at the login endpoint does not get around the removed form. The rejection is recorded at info level, see Logging.
It is all-or-nothing per scope. There is no per-user exemption, and tx_sso_enabled is not one—see tx_sso_enabled.
enforceSSO is a YAML-only option. An XML configuration file is plain identity provider metadata with no place for a TYPO3 setting; if you use XML, switch to YAML and point idp at your metadata URL instead.
Losing the Identity Provider
The Install Tool is the way back in. It authenticates against the install tool password in config/system/settings.php, entirely independently of be_users and of this extension, and it stays reachable no matter what the identity provider does. From there you can clear BackendServiceProviderConfigurationFile, or turn enableBE off, and the regular login screen returns.
Two consequences worth acting on before you enable enforcement:
- Confirm that access first. An install tool password nobody has, or an
ENABLE_INSTALL_TOOLfile the deployment removes, turns an identity provider outage into an installation nobody can administer. - Keep the extension configuration editable without the backend. Setting it in
config/system/settings.phporadditional.phpmeans a deploy or a shell can undo it; setting it only through the Extension Configuration form in the Settings module means you need the backend to reach it.
When the Setup Is Incomplete or Broken
The behavior here is deliberate: a configuration that cannot be resolved never locks anybody out.
| Situation | What You Get |
|---|---|
enableBE off | No SSO entry, no authentication service. The regular login, unchanged |
| No configuration file set | The same. Enforcement cannot apply either, because the setting lives in the file that was never read |
| File set but not resolvable | The same again—enforcement is only ever true once the file has actually been loaded |
| File resolves, but the SAML settings are rejected | The login screen shows Login with SSO is currently not available. and hides the submit button. The reason is logged at error level |
| Metadata endpoint requested with invalid settings | HTTP 503 with the toolkit’s validation errors in the message |
The fourth row is the case to watch, because it is the only one that does leave you without a usable login screen when enforcement is on: the configuration loaded, so enforcement applies and the password provider is gone, but the settings do not produce a valid authentication request. Requesting the metadata endpoint is the fastest way to see the same validation errors as a message rather than as a missing button—see Smoke Test.
Editing a Backend User
With enableBE on, the be_users password field is no longer required, so a user record can exist without one. The field is additionally hidden whenever tx_sso_enabled is checked, and a warning badge appears on that checkbox when it is set on an existing user missing either tx_sso_tenantid or tx_sso_objectidentifier—that is, one who has not completed an SSO login that filled them in. The badge is a hint to the editor, nothing more; see the tx_sso_* columns.