Documentation

There are three configuration sources, and which one a key belongs in is not a matter of taste:

The backend has no site context at login time, which is why it reads TYPO3-specific settings from its configuration file while the frontend reads them from the site configuration. The same key therefore lives in two different places depending on scope, and this chapter states which for every one of them.

BackendServiceProviderConfigurationFile for the backend, the site setting metadata for the frontend. Three forms are accepted:

A path that is neither EXT:-prefixed nor a URL is treated as a URL and fails.

YAML files may nest everything under a single sso_typo3: root key, which is then unwrapped. Without that key the file is read as-is.

idp is required in a YAML file and has to be a string. It is either the metadata URL of the identity provider—fetched and parsed on use—or any other string. An inline idp: block in the toolkit’s own nested notation is not supported here and fails; see Known Limits.

Everything in this table is read by the extension itself. Where a key exists in both scopes, the two locations are given.

For the frontend, the site configuration contributes exactly the keys marked "site config" above. Everything else has to be in the configuration file—idp, allowEmailAsUsername, NameIDFormat, strict, organization, and any security key beyond the four listed. A top-level x509cert, federation or claimsMapping in a frontend configuration file is not read; those come from the site configuration only.

Anything else in the configuration file reaches onelogin/php-saml untouched. The two worth knowing:

• strict rejects unsigned or unencrypted messages where a signature or encryption is expected, instead of accepting them with reduced security. This extension never reads it; leave it alone unless you know why you are turning it off.
• organization shows up in the generated metadata and is otherwise inert.

A nested sp: block has no effect. entityId, assertionConsumerService and singleLogoutService are assembled from the base URL plus the top-level entityId and acsUrl, and the computed values overwrite whatever the block says. sp.NameIDFormat is overwritten the same way by the top-level key.

The single logout URL is generated in both scopes and cannot be configured. For the backend it is the entry point plus ?logintype=slo, for the frontend the site base plus ?logintype=slo.

Despite the name in the extension configuration form, this only takes effect when entityId resolves to a value containing no ://—the assertion consumer service and single logout URLs are already absolute by the time it is applied. So it matters in exactly one case: a configuration that sets a relative entityId such as '/' and needs it prefixed with a specific host, for instance because the backend is reachable under several domains. Leave both empty and the default entity ID—the backend entry point of the current request—is used, which is the right answer for a single-domain installation.

It applies to the frontend as well, even though the name says backend: a relative entityId in a site configuration is prefixed with the same value.

claimsMapping maps an incoming SAML attribute name to a column of be_users or fe_users. Two forms:

Attribute names may be written short. The namespace prefixes schemas.microsoft.com/claims/, schemas.microsoft.com/identity/claims/ and schemas.xmlsoap.org/ws/2005/05/identity/claims/ are stripped before matching, so displayname and the full URI are equivalent keys.

A multi-valued attribute is joined with | before mapping. A single value is used as-is.

valueMapping is a filter, not just a translation. Only incoming values listed there are used; everything else is dropped. The results are joined with a comma, which is what makes it suitable for usergroup. Without a valueMapping, the raw value is written to the column verbatim.

A mapping with an empty field name is skipped, which is how you switch a default off.

One entry is applied before yours and can be overridden: schemas.microsoft.com/identity/claims/displayname maps to realName in the backend and to name in the frontend.

Three of the keys above are the ones worth a second look before going live.

userStoragePid in the backend. TYPO3 only looks up be_users at the root of the page tree. A backend user federated onto any other page is invisible to every later login, so federation creates a fresh duplicate each time somebody signs in—growing be_users by one row per login, each with the group assignment the claims currently produce. Keep it at 0. In the frontend the same setting is required to be your fe_users folder instead, because a frontend login is restricted to it.

enforceSSO without a tested way back in. It removes the password login for the whole scope, with no per-user exemption. If the identity provider becomes unreachable, nobody signs into the backend until it returns—except through the Install Tool, which has its own authentication. Confirm that access before you switch enforcement on, see Losing the Identity Provider.

allowEmailAsUsername left on after a migration. It exists so users created with an email address as their username can be matched. TYPO3 does not enforce uniqueness on email, so as soon as two active users share an address a login can bind to the wrong record—which means the wrong person’s permissions. Turn it off once the migration is done.

These are properties of the current implementation, not settings:

• A YAML configuration file needs a top-level idp string. An inline idp block in the toolkit's nested notation, or a missing idp key, aborts resolution of the file.
• loginStatusPage and noGroupsPage are read directly from the site configuration at the point they are needed, not through the configuration file. Leave loginStatusPage unset and a logout lands on the site's root page; leave noGroupsPage unset and a visitor without groups is not redirected at all. Set both on any site that uses frontend logout or group-gated access — the fallbacks keep the site working, they do not do the job the pages are there for.
• Backend single logout is not implemented. The URL is generated into the metadata, but nothing handles it.