TYPO3 v14

Handbuch

Keycloak-Client einrichten

Schritt für Schritt mit Screenshots: Client typo3-v14 im Realm sonia anlegen – Zugriff, Protokoll, Abmeldung, Client-Secret, Rollen, Mapper und Client Scopes.

Worum es geht

TYPO3 meldet sich bei Keycloak als vertraulicher OpenID-Connect-Client an. Diese Seite beschreibt den Client typo3-v14 im Realm sonia so, wie er in der lokalen SONIA-Umgebung eingerichtet ist. Die Screenshots zeigen die deutsche Oberfläche der Keycloak-Admin-Konsole (Keycloak 26) unter https://id.dev.sonia.de/admin/.

Den Client legt man unter Clients → Client erstellen an (Typ OpenID Connect, Client-ID typo3-v14) und füllt danach die Reiter wie unten beschrieben aus. Auf einem Server ersetzt man http://typo3-v14.localhost:8088 durch die öffentliche Adresse der TYPO3-Installation.

Was TYPO3 mit den Rollen und Abmeldungen macht, steht auf der Seite „Anmeldung über Keycloak“.

1. Zugriffseinstellungen

Reiter Einstellungen, Abschnitt Zugriffseinstellungen:

FeldWertHinweis
Root URL, Home-URLhttp://typo3-v14.localhost:8088Basis für relative Adressen
Valid redirect URIs/*relativ zur Root URL; TYPO3 kehrt nach dem Login nach /typo3/… zurück
Valid post logout redirect URIshttp://typo3-v14.localhost:8088/typo3/loginZiel nach dem Single Logout
Web Originsbeliebigwird nicht benötigt: Der Login läuft serverseitig, nicht per JavaScript
Admin URLbeliebigwird von TYPO3 nicht verwendet
Keycloak, Client typo3-v14, Reiter Einstellungen: Allgemeine Einstellungen und Zugriffseinstellungen
Einstellungen → Allgemeine Einstellungen und Zugriffseinstellungen

2. Protokolleinstellungen

  • Client-Authentifizierung: An – vertraulicher Client mit Client-Secret (Schritt 4).
  • Autorisierung: Aus
  • Authentifizierungsablauf: nur Standard-Flow (Authorization Code). Direct access grants, Implicit flow und die übrigen Verfahren bleiben aus.
  • Erzwinge PKCE: An, PKCE Methode: S256 – causal/oidc sendet die PKCE-Parameter mit (enableCodeVerifier in additional.php).
  • Erzwinge DPoP: Aus
Keycloak, Protokolleinstellungen: Client-Authentifizierung an, nur Standard-Flow, PKCE erzwungen mit S256
Einstellungen → Protokolleinstellungen

3. Abmeldeeinstellungen

FeldWert
Abmeldung über Front-ChannelAus
Back-Channel Abmelde-URLhttp://host.docker.internal:8088/oidc/backchannel-logout
Back-Channel-Abmeldung für Sitzung erforderlichAn (Pflicht)
Back-Channel-Abmeldungen widerrufen Offline-SitzungenAus
Logout confirmationAus

Keycloak läuft lokal im Docker-Netz lr7 und erreicht TYPO3 über host.docker.internal:8088. Auf einem Server trägt man die öffentliche TYPO3-Adresse ein.

TYPO3 ordnet Logout-Tokens ausschließlich über die Keycloak-Session-ID sid zu. Ohne „Sitzung erforderlich“ fehlt die sid, und TYPO3 lehnt das Token mit 400 ab. Mit „Logout confirmation“ zeigt Keycloak nach dem Abmelden eine Bestätigungsseite, statt zur TYPO3-Login-Seite zurückzuleiten.

Danach unten auf Speichern klicken.

Keycloak, Abmeldeeinstellungen: Front-Channel aus, Back-Channel-Abmelde-URL eingetragen, Sitzung erforderlich an
Einstellungen → Abmeldeeinstellungen

4. Client-Secret in die .env übernehmen

Reiter Zugangsdaten: Client-Authentifikator „Client Id and Secret“, das Client-Secret kopieren und in die .env der Appliance eintragen:

TYPO3_OIDC_ISSUER=https://id.dev.sonia.de/realms/sonia
TYPO3_OIDC_CLIENT_ID=typo3-v14
TYPO3_OIDC_CLIENT_SECRET=<Client-Secret>

Danach docker compose up -d. Das Secret gehört nur in die .env, nie in versionierte Dateien, Tickets oder Screenshots.

5. Client-Rollen anlegen und zuweisen

Reiter Rollen → Rolle erstellen: die Rollen admin und editor anlegen (ohne Zusammensetzung).

Zuweisen unter Benutzer bzw. Gruppen → Reiter Rollenzuweisung → Rolle zuweisen, dort nach Client-Rollen filtern und typo3-v14 admin oder typo3-v14 editor wählen. Benutzer ohne eine dieser Rollen werden in TYPO3 nicht angelegt.

Keycloak, Reiter Rollen des Clients typo3-v14 mit den Rollen admin und editor
Rollen → Client-Rollen admin und editor

6. Mapper für den Claim „Roles“

Reiter Client Scopes → typo3-v14-dedicated → Mapper hinzufügen → Nach Konfiguration → User Client Role:

FeldWert
NameRoles
Client-IDtypo3-v14
Client Role prefixleer
Mehrere WerteAn
Token Claim NameRoles (großes R)
Claim JSON-TypString
Add to ID token, access token, lightweight access token, token introspectionAus
Zur UserInfo hinzufügenAn

causal/oidc liest die Rollen ausschließlich aus dem Claim Roles der Userinfo-Antwort. In den Tokens werden sie nicht gebraucht.

Keycloak, Mapper „Roles“ vom Typ User Client Role: Client-ID typo3-v14, mehrere Werte an, Token Claim Name Roles, nur zur UserInfo hinzufügen an
Client Scopes → typo3-v14-dedicated → Mapper „Roles“

7. Client Scopes prüfen

Zugeordnet sind typo3-v14-dedicated (mit dem Mapper aus Schritt 6), acr, basic und profile als Standard sowie email als optional. TYPO3 fordert openid profile email an (TYPO3_OIDC_SCOPES) und erhält damit auch die E-Mail-Adresse.

Im Realm sonia setzt der Scope profile den stabilen Benutzernamen (soniaExternalUid, eid…) als preferred_username. Darüber ordnet TYPO3 die Backend-Benutzer zu; die interne Keycloak-ID ändert sich bei jedem LDAP-Neuimport.

Prüfen lässt sich das Ergebnis unter Client Scopes → Auswerten: Benutzer wählen, dann zeigt die generierte Userinfo die Claims preferred_username und Roles.

Keycloak, Reiter Client Scopes: typo3-v14-dedicated, acr, basic und profile als Standard, email optional
Client Scopes → zugeordnete Scopes

8. Testen

  1. http://typo3-v14.localhost:8088/typo3/ öffnen: Der OIDC-Login ist vorausgewählt und leitet zu Keycloak weiter.
  2. Nach der Anmeldung landet man im Backend. Der Benutzer heißt wie preferred_username und gehört zur Gruppe „Admin (Keycloak)“ oder „Editor (Keycloak)“.
  3. Abmelden im Backend meldet auch bei Keycloak ab (Single Logout). Umgekehrt beendet „Abmelden“ in der Keycloak-Kontoverwaltung oder das Löschen der Sitzung in der Admin-Konsole die TYPO3-Sitzung (Back-Channel).

Ergebnisse protokolliert oidc_backend in var/log/typo3_oidc_*.log. Fehlerbilder und Debug-Logging stehen auf der Seite „Anmeldung über Keycloak“.