Zum Inhalt

KCForms in ein Portal integrieren (Konzept)

Konzept — Stand September 2026

Diese Seite beschreibt, wie sich KCForms in ein umgebendes Portal (z. B. ein Bürgerportal hinter einem Reverse-Proxy) einbetten lässt: was heute schon geht, was noch fehlt und welche Entscheidungen offen sind. Sie ist keine Anleitung für eine fertige Funktion. Seit der ersten Fassung (Juli 2026) ist die Anmeldung per OIDC hinzugekommen; das verkleinert die Lücke beim Single Sign-on deutlich.

Kurzüberblick: fünf Integrationsdimensionen

Dimension Ist-Zustand Reifegrad Größte Lücke
Authentifizierung / SSO 5 Anmelde-Strategien inkl. OIDC; Skript-Login sieht HTTP-Header gut kein „stiller" Auto-Login per Header-/Token-Übergabe, kein SAML
Einbettung / Deep-Linking ?form=- und Ad-hoc-Links; Einbetten in iframes von der eigenen Adresse und von freigegebenen Portal-Adressen gut Cookie SameSite=Lax bricht iframes über Site-Grenzen
Datenaustausch (in/out) REST-Services + onSubmit-Webhooks + Transport gut — (durch REST-Feature abgedeckt)
Branding Theme-Runtime-CSS zentral pflegbar gut —
Betrieb Health-Check, Wartungsfenster, Base-URL gut CORS hart auf localhost verdrahtet

Kernaussage: Der Großteil der Integration ist mit Konfiguration + Scripting + einem Reverse-Proxy machbar — ohne Änderung am Code. Hat das Portal einen OpenID-Connect-Anbieter, genügt die vorhandene OIDC-Anmeldung. Code-Arbeit bleibt nur für eine Übergabe per Header oder eigenem Token (siehe Roadmap).

Empfohlene Zielarchitektur

Reverse-Proxy unter einer gemeinsamen Außendomain (z. B. portal.example.se/forms/ → KCForms) + Anmeldung über den Portal-Anbieter (OIDC) oder SSO-Übergabe + REST für Daten + onSubmit-Webhooks für Events + Theme fürs Look-&-Feel.

Der Entscheid „gemeinsame Domain hinter Proxy" räumt drei Probleme auf einen Schlag ab:

  • Cookie SameSite — die Sitzung gehört zur selben Site, Lax reicht (auch im iframe).
  • CORS — Anfragen kommen vom selben Ursprung; die fest auf localhost eingestellte Liste spielt keine Rolle.
  • iframe — Einbettung nur von Adressen, die KCForms erlaubt: von sich selbst immer, vom Portal nach Freigabe (siehe Einbetten erlauben).

Getrennte Domains sind möglich, ziehen aber Zusatzarbeit nach sich (SameSite=None; Secure, konfigurierbares CORS).

Einbetten erlauben

KCForms lässt sich nur von der eigenen Adresse in einen iframe einbetten. Damit kann keine fremde Seite das Formular unsichtbar überlagern und Klicks abfangen (Clickjacking). Soll ein Portal KCForms einbetten, trägst du seine Adresse ein:

KCFORMS_SECURITY_FRAME_ANCESTORS=https://portal.example.com

Mehrere Adressen trennst du mit Komma, https://*.example.com erlaubt alle Unteradressen. Erlaubt sind nur Adressen der Form https://name[:port]; ein anders geschriebener Eintrag wird ignoriert. Nach der Änderung KCForms neu starten.

Seit dem Stand vom 18.10.2026

Bis dahin war das Einbetten von jeder Seite aus erlaubt. Bettet ein Portal auf einer anderen Adresse KCForms schon ein, bleibt der iframe nach dem Update leer, bis die Portal-Adresse eingetragen ist.

Die fünf Dimensionen im Detail

1. Authentifizierung / SSO

Vorhanden: DB-Login (Standard), Fixed-Login (Entwicklung), Skript-Login (frei programmierbar), BankID und OIDC / Broker, dazu der Notfall-Modus — siehe Anmeldung. Hat das Portal einen OpenID-Connect-Anbieter (Keycloak, Azure AD, ein BankID-Broker …), meldet OIDC die Benutzer dort an; unbekannte Personen können dabei automatisch angelegt werden. Skript-Login bekommt die HTTP-Header und die IP-Adresse — damit ist auch eine eigene Token-Prüfung ohne Code-Änderung möglich. SAML gibt es nicht.

Zielbild „SSO durch Übergabe aus dem Portal": Das Portal authentifiziert den Nutzer (zunächst gegen LDAP/AD) und übergibt die Identität an KCForms; ein Pre-Authentication-Filter prüft die Übergabe, baut die Session ohne Login-Maske auf und mappt via LDAP die Gruppen auf KCForms-Rollen/-Rechte.

Wege offenhalten: den Verifizierer als austauschbaren Baustein bauen — heute AD-/Token-Handover, später ein OIDC-JWT gegen die IdP-JWKS (das http-Binding kann die JWKS bereits holen), ohne den Filter neu zu schreiben.

2. Einbettung & Deep-Linking

  • Direkter Formular-Link: https://<host>/?form=<formId> öffnet ein Formular.
  • Web-Links: /adhoc/<id> öffnet ein Formular oder einen Datensatz, mit Zugriffsstufe je Link (anonymous, public, any, user:…, group:…) und Ablaufdatum — ideal für Portal-Kacheln und Aufgabenlisten.
  • iframe funktioniert same-domain problemlos; der iframe-src trägt bei Bedarf den Handover-Token.
  • Beide Wege (iframe und Vollbild-Redirect) sind vorgesehen.

3. Datenaustausch

  • Portal → KCForms: die REST-Services (frei per JS, Swagger, per-Service- Token) — Formulare, Instanzen, Kennzahlen lesen/schreiben, ohne Deployment. Siehe REST-Services.
  • KCForms → Portal: onSubmit/onAfterSave-Hooks + http/ws-Bindings = Webhooks beim Absenden. Dateien via delivery.
  • Formular-Definitionen ausrollen: Transport DEV → QS → PROD (/api/transport/inbound, Bearer-Token).

4. Branding

Theme: Markenfarben und eigenes CSS zentral, wirken auch auf Anmelde- und Web-Link-Seiten. Anpassung ans Portal ist reine Konfiguration.

5. Betrieb / Netzwerk

  • Health-Check fürs Portal-Monitoring: GET /api/rest/service/health (Liveness) und …/health/ready (Readiness inkl. DB, 200/503).
  • Wartungsfenster (Banner + Sperre für Nicht-Administratoren).
  • Öffentliche Basis-URL (system.publicBaseUrl) setzen, damit Mail- und Web-Links die Portal-Adresse tragen.
  • CORS ist fest auf localhost eingestellt — bei getrennten Domains mit direktem Browser-Zugriff eine Lücke; beim Reverse-Proxy-Ansatz ohne Bedeutung.

SSO-Handover: Entscheidungsvorlage

Hat das Portal keinen OIDC-Anbieter, muss es die Identität anders übergeben. Wie, bestimmt die Prüfung in KCForms. Drei Varianten:

Kriterium A) Vertrauens-Header via Proxy B) Signierter Token / JWT C) HMAC-Token im Link
Portal/Proxy muss können Proxy setzt Header und strippt Client-Kopien Portal erzeugt signierten Token (HMAC/JWT) Portal hängt kurzlebigen HMAC-Token an die URL
KCForms prüft „kommt vom Proxy-Netz" Signatur + Ablauf + Audience Signatur + Ablauf des URL-Tokens
Sicherheits-Anker Netz-/Proxy-Vertrauen (fragil bei Fehlkonfig) kryptografisch (stark) kryptografisch (stark)
Größter Fallstrick Header-Spoofing, wenn der Proxy Kopien nicht entfernt Schlüssel-/Secret-Management Token in URL → Logging/Referrer, daher sehr kurzlebig + einmalig
iframe + Deep-Link beides beides beides (URL-getragen)
KCForms-Aufwand am geringsten mittel mittel
Später auf OIDC umstellen Neuanfang naheliegend (JWT wie bei OIDC) Neuanfang

Empfehlung: den Verifizierer austauschbar bauen und mit der Variante starten, die das Umfeld am einfachsten liefert:

  • Gibt es einen OIDC-Anbieter → vorhandene OIDC-Anmeldung, keine Code-Arbeit.
  • Proxy meldet selbst gegen AD an und kann Header sauber setzen und entfernen → A.
  • sonst → B (signierter Token).

Roadmap

Phase Inhalt Art Aufwand
0 — Topologie Reverse-Proxy …/forms/ → KCForms, TLS, system.publicBaseUrl, Theme Betrieb/Konfig niedrig
1 — Anmeldung mit OIDC-Anbieter: OIDC / Broker einrichten (Konfiguration). Ohne: Pre-Auth-Filter + Token-/Header-Prüfung + LDAP-Gruppen→Rechte Konfiguration bzw. Backend-Feature niedrig bzw. mittel
2 — Einbettung Portal baut Deep-Links (?form=, ?adhoc=) und iframe-src mit Token; Portal-Adresse unter Einbetten erlauben eintragen Konfig + Portal-Seite niedrig
3 — Datenflüsse Portal-spezifische REST-Services + onSubmit-Webhook Admin-Scripting niedrig
4 — Härtung Token-Replay/Ablauf, Logout-Kopplung, Session-Lebensdauer, OIDC-Pfad vorbereiten Betrieb + klein niedrig–mittel

Alles außer der Header-/Token-Variante von Phase 1 ist Konfiguration oder Scripting.

Offene Fragen ans Portal-/Proxy-Team

  1. Authentifiziert der Proxy selbst gegen AD, oder nur das Portal dahinter?
  2. Kann der Proxy Request-Header setzen und eingehende Client-Kopien zuverlässig strippen?
  3. Kann das Portal einen signierten Token/JWT erzeugen — mit welchem Verfahren (HMAC-Shared-Secret? RSA/JWKS)?
  4. Gibt es einen OpenID-Connect-Anbieter (Keycloak, Azure AD …)? Dann reicht die vorhandene OIDC-Anmeldung.
  5. Wie soll Logout gekoppelt sein (Portal-Logout beendet die KCForms-Session)?
  6. Welche AD-Gruppen sollen auf welche KCForms-Rollen/Rechte mappen?

Sobald diese Punkte geklärt sind, lässt sich aus dieser Einschätzung ein umsetzbarer Plan für Phase 1 ableiten (Filter-Design, Konfig-Keys, Proxy-Snippet, Beispiel-Login-/Mapping-Skript).