OIDC for TYPO3

How TYPO3 projects without their own identity stack connect to Azure AD, Keycloak or Okta

In any company that runs Microsoft 365, Google Workspace or a central Keycloak, the user management question has long been settled: all staff accounts live in the IdP, and every new application should plug in there rather than managing its own passwords. The OIDC extension for TYPO3 serves exactly this pattern by embedding OpenID Connect as an auth protocol in TYPO3 and making Azure AD, Keycloak, Okta, Google Workspace or Auth0 usable as an IdP, without having to run a dedicated Shibboleth SP. The target audience are corporate portals, intranets, customer login areas and any TYPO3 setup that needs to sit inside an existing enterprise identity landscape.

Typical use cases

A mechanical engineering group with 14,000 employees runs its staff intranet on TYPO3. IT operations decided long ago that every new application has to authenticate against Azure AD and enforce multi-factor authentication there. The OIDC extension fetches the ID tokens from Azure AD, reads the group memberships included in the claim and turns them into fe_user groups. The intranet gains single sign-on, MFA and conditional access without any additional infrastructure, purely through clean configuration.

A second scenario comes from the mid-market: a software vendor with a customer portal on TYPO3 uses Keycloak as a central broker because its customers arrive with usernames or with social logins such as Google or GitHub. Keycloak unifies the situation and speaks OIDC on the outside. TYPO3 uses the OIDC extension and gains access to all login variants without having to know that social login is happening behind the scenes.

The third case is public administration and regional governments moving to Keycloak-based citizen accounts. A TYPO3 portal through which citizens submit application forms can connect to the regional Keycloak via the OIDC extension. The eID attribute from the broker lands directly in the fe_user, and the authentication level can be evaluated via the acr claim.

Technical architecture: authorisation code flow in TYPO3

OpenID Connect is an authentication layer on top of OAuth 2.0, and the OIDC extension implements exactly the authorisation code flow. The sequence is simpler than SAML: TYPO3 redirects the user to the IdP with an authorisation request, receives a code back after a successful login, exchanges that code server-side for an ID token and validates the signature via the provider’s JSON Web Key Set (JWKS). The claims from the ID token, typically sub, email, name, groups and roles, are mapped to TYPO3 user fields.

The extension is configured through the TYPO3 extension configuration and a discovery endpoint that every OIDC-compliant provider exposes at /.well-known/openid-configuration. The extension reads the token endpoints, the JWKS URL and the supported flows automatically from that URL, which reduces manual errors. Claim mapping is handled via a YAML or TypoScript configuration that maps local field names to claim paths.

Common problems and solutions

The first problem concerns claim formats: Azure AD delivers groups as object IDs (GUIDs), not as readable names. If you expect a claim group_ids and receive group_names, you see empty user groups in TYPO3. The clean solution lies in the Azure AD application itself: in the token configuration blade you can define which attributes are issued as claims, and a claim transformation rule set can translate GUIDs into readable names.

The second problem is the redirect URI. Every OIDC client has to register the exact redirect URI with the IdP to which it will be sent after login. Differences in upper and lower case, forgotten trailing slashes or a switch from HTTP to HTTPS cause immediate login errors that are invisible in the TYPO3 log because the error happens at the IdP. Gosign configures separate clients with clean redirect URIs for staging and production and documents every change in the deployment process.

The third topic is token refresh. Anyone who wants longer sessions needs refresh tokens, which the IdP only issues if the offline_access scope has been requested at login. Without that scope, the TYPO3 session ends as soon as the ID token expires, usually after an hour. The extension backend configuration therefore has to include the offline_access scope and activate the token refresh logic.

A fourth problem concerns logout. OIDC knows front-channel and back-channel logout, and both are not necessarily enabled in the extension. Anyone expecting true single logout across multiple applications has to configure the provider’s end-session endpoint and make sure that TYPO3 calls the IdP’s logout URL at the end of the session. Without that configuration, the user remains logged in at the IdP even though they have signed out of TYPO3.

Migration and version compatibility

The OIDC extension is currently the recommended standard for TYPO3 v12 and v13, while older v11 projects often still rely on hand-built OAuth implementations or shibboleth_auth. The migration path from Shibboleth to OIDC is well established, provided the IdP speaks both: Keycloak, ADFS and Azure AD can serve SAML and OIDC in parallel, so a transition without a big bang is possible.

Anyone migrating from a purely database-backed fe_user management has to map the existing accounts onto the OIDC claims with a matching strategy. The email address is the usual anchor but is not always enough, because email addresses change. A sub claim, stored as a unique persistent identifier in the fe_user, is the more robust solution. Gosign handles these migrations including reconciliation of existing accounts and a transition phase during which both auth paths work in parallel.

For teams just starting a new TYPO3 project, OIDC is the first choice in most cases. The configuration is leaner than SAML, the client effort lower, and every modern IdP supports the protocol natively. Exceptions are only justified where regulatory or federation requirements explicitly demand SAML, such as in the academic federations mentioned above. In every other scenario, especially with cloud-based IdPs and enterprise integrations, OIDC offers the better trade-off between simplicity, security and maintainability.