Anmeldung¶

Wie sich Benutzer an KCForms anmelden, legt eine Anmelde-Strategie fest. Welche aktiv ist, stellst du unter System-Administration → Benutzer & Zugang → Anmeldung ein.

flowchart TD
    L[Anmeldeversuch] --> N{Notfall-Modus<br/>eingeschaltet?}
    N -- ja --> E[Nur das Notfall-Konto]
    N -- nein --> S{aktive Strategie}
    S --> DB[DB-Login]
    S --> FX[Fixed-Login]
    S --> SC[Skript-Login]
    S --> BI[BankID]
    S --> OI[OIDC / Broker]
    S --> SA[SAML 2.0]

Strategie	Wofür
DB-Login (Standard)	Anmeldename und Passwort gegen die Benutzer in KCForms
Fixed-Login	meldet ohne Passwort immer denselben Benutzer an — nur für die Entwicklung
Skript-Login	eigene Logik in JavaScript, z. B. LDAP/Active Directory
OIDC / Broker	Anmeldung über einen OpenID-Connect-Anbieter (z. B. BankID über einen Broker) — siehe unten
SAML 2.0	Anmeldung mit dem Konto der Hochschule (SWAMID, DFN-AAI, eduGAIN) — siehe SAML-Anmeldung

Eine Strategie, die noch nicht eingerichtet ist, erscheint in der Auswahl als „(nicht verfügbar)".

Anmeldename und Passwort werden gegen die Tabelle users geprüft (Passwörter als BCrypt-Hash). Keine Einrichtung nötig. Benutzer pflegst du unter Benutzer & Gruppen.

Ignoriert das Passwort und meldet immer denselben, fest eingestellten Benutzer an. Doppelt abgesichert:

Der Server muss es erlauben: kcforms.auth.allow-fixed-login=true (Umgebungsvariable KCFORMS_AUTH_ALLOW_FIXED_LOGIN=true).
Erst dann lässt sich die Strategie auswählen.

Ist Fixed-Login aktiv, zeigt die Anmeldeseite eine rote Warnung und einen Knopf „Direkt anmelden".

Ein Anmelde-Skript bekommt die Eingaben und entscheidet selbst. Skripte legst du auf der Anmelde-Seite im Bereich Auth-Skripte an (+ Neues Skript, Titel, Beschreibung, Code, Skript speichern) und wählst das gewünschte oben unter Aktives Auth-Skript aus.

Im Skript	Inhalt
`auth.username`	eingegebener Anmeldename
`auth.password`	eingegebenes Passwort
`auth.headers`	HTTP-Header (Namen klein geschrieben)
`auth.remoteAddr`	IP-Adresse des Aufrufers
`auth.success(benutzer, gruppen[], rechte[])`	Anmeldung erlauben
`auth.fail(code, meldung)`	ablehnen
`auth.fallbackToDb()`	normalen DB-Login durchführen
`db`, `ldap`, `log`, `kc`	wie in anderen Skripten

Ein Skript muss am Ende genau eine der drei auth.*-Entscheidungen treffen. Die Vorlage für ein neues Skript:

if (!auth.username) {
  auth.fail("missing_username", "Bitte Benutzername angeben.");
} else {
  // var rows = db.query("SELECT 1 FROM whitelist WHERE login = ?", auth.username);
  // if (rows.length === 0) { auth.fail("not_in_whitelist"); } else {
  //   auth.success(auth.username, ["ADMIN"], ["SAP_ACCESS"]);
  // }
  auth.fallbackToDb();
}

Ein vollständiges Beispiel für LDAP/Active Directory steht unter LDAP-Zugriff.

Mitgeliefertes Skript „Kaskadierter LDAP + DB-Login"

KCForms legt dieses Skript bei jedem Start an bzw. setzt es auf den mitgelieferten Stand zurück. Es versucht zuerst LDAP und fällt sonst auf den DB-Login zurück. Eigene Anpassungen deshalb in einer Kopie unter anderem Titel vornehmen.

Im Bereich Test-Login gibst du Benutzer und Passwort ein und startest Test ausführen. Geprüft wird die ausgewählte Strategie, ohne dich anzumelden oder etwas umzustellen; bei Skript-Login wird der aktuelle Inhalt des Editors verwendet — das Skript muss dafür noch nicht gespeichert oder aktiv sein. Jeder Test landet im Audit-Protokoll.

Erst testen, dann umstellen

Stelle die Strategie erst auf Skript-Login, wenn der Test-Login mit einem normalen Benutzer und mit einem Administrator klappt. Sonst sperrst du dich womöglich aus — dann hilft nur der Notfall-Modus.

Hinweis auf der Anmeldeseite¶

Bei Skript-Login verrät die Anmeldeseite standardmäßig nicht, wie die Anmeldung technisch läuft. Den gelben Hinweis „Skript-Login aktiv …" (etwa für Testsysteme) schaltest du unter Betrieb & Überwachung → System-Einstellungen → Skript-Login-Hinweis im Login-Screen ein. Die rote Warnung bei Fixed-Login erscheint immer.

Unten auf der Anmelde-Seite pflegst du einen freien Text, der unter dem Knopf „Anmelden" erscheint — je Sprache (Deutsch, Svenska, English …), mehrzeilig. Typisch für Test- und Demosysteme („Demo-Zugang: …"). Der Schalter Login-Hinweis anzeigen blendet ihn ein oder aus, ohne den Text zu löschen. Speichern mit Login-Hinweis speichern. Denselben Text findest du unter Sprachen beim Schlüssel login.hint.

Keine Passwörter auf Produktivsystemen

Der Hinweis ist für alle sichtbar, die die Anmeldeseite öffnen. Auf Produktivsystemen ausschalten.

Unter Benutzer & Zugang → OIDC (Entra ID, AD FS, BankID-Broker) richtest du die Anmeldung über einen OpenID-Connect-Anbieter ein — etwa BankID über einen Broker, ohne eigenes Zertifikat. Das Modul ist vorbereitet, aber ausgeschaltet.

Windows-Anmeldung (Single Sign-On)

Für die Anmeldung mit dem Windows-Konto über Microsoft Entra ID, AD FS oder Keycloak gibt es eine eigene Seite: Windows-Anmeldung.

OIDC-Modul aktiv einschalten und die Angaben des Anbieters eintragen: Issuer-/Discovery-URL, Client-ID, Client-Secret, Redirect-URI (beim Anbieter zu registrieren), Scopes, bei Bedarf acr_values.
Zuordnung festlegen: welcher Claim die Personennummer bzw. den Namen liefert, ob unbekannte Personen automatisch als neue Benutzer angelegt werden (mit welchen Standard-Gruppen) und die Beschriftung des Anmelde-Knopfs.
Verbindung testen (Discovery) prüft, ob der Anbieter erreichbar ist.
Unter Anmeldung die Strategie auf OIDC stellen.

Sitzung¶

Eine Sitzung endet nach 30 Minuten ohne Aktivität (Countdown oben rechts). Läuft sie während der Arbeit ab, erscheint auf der Anmeldeseite „Ihre Sitzung ist abgelaufen". Beim normalen Öffnen der Anwendung erscheint der Hinweis nicht.

Sperre nach Fehlversuchen¶

Nach 5 falschen Passwörtern für denselben Anmeldenamen ist dieser Name für 15 Minuten gesperrt. Die Anmeldeseite zeigt dann „Zu viele Fehlversuche“ mit der Wartezeit — auch das richtige Passwort wird in dieser Zeit nicht angenommen. Danach geht es von selbst wieder; niemand muss etwas freischalten.

Gezählt wird der eingegebene Name, ob es ihn gibt oder nicht. So verrät die Sperre nicht, welche Anmeldenamen existieren.
Zusätzlich gilt eine Grenze je Absender-Adresse (30 Fehlversuche in 15 Minuten). Sie bremst das Durchprobieren vieler Namen mit einem häufigen Passwort.
Die Sperre ist bewusst vorübergehend. Eine dauerhafte Sperre könnte jeder Fremde nutzen, um gezielt Konten stillzulegen — auch das des Administrators. Dauerhaft sperren kannst du ein Konto in der Benutzerverwaltung.
Sie gilt für jede Anmelde-Strategie und auch für den Notfall-Modus.
Der Zähler liegt im Arbeitsspeicher: Ein Neustart setzt ihn zurück, und bei mehreren Instanzen hinter einem Lastverteiler zählt jede für sich.

Hinter einem Reverse Proxy

Die Absender-Adresse liest KCForms aus X-Forwarded-For. Das ist richtig, solange davor ein Proxy steht, der diesen Header selbst setzt. Ist KCForms direkt aus dem Internet erreichbar, kann ein Angreifer den Header fälschen und die Adress-Grenze umgehen; die Grenze je Name bleibt wirksam.

Notfall-Modus¶

Wer sich durch ein fehlerhaftes Anmelde-Skript ausgesperrt hat, schaltet den Notfall-Modus über Umgebungsvariablen ein und startet KCForms neu:

KCFORMS_AUTH_EMERGENCY=true
KCFORMS_AUTH_EMERGENCY_USER=notfall
KCFORMS_AUTH_EMERGENCY_PASSWORD=<eigenes-starkes-Passwort>

Solange er aktiv ist, ignoriert KCForms die eingestellte Strategie und akzeptiert nur dieses eine Konto; es bekommt die Gruppe ADMIN. Damit meldest du dich an, korrigierst die Einstellung und schaltest den Modus wieder aus (KCFORMS_AUTH_EMERGENCY=false, Neustart).

Nur mit eigenem Passwort

Ohne eigene Werte gälten admin / admin — jeder, der das weiß, hätte Administratorrechte. Deshalb nimmt der Notfall-Modus das Standardpasswort nicht an, ebenso kein Passwort mit weniger als 12 Zeichen: Die Anmeldung wird dann abgewiesen, und das Server-Protokoll sagt beim Start, warum. Den Modus nur so kurz wie nötig eingeschaltet lassen. Solange er aktiv ist, können sich alle anderen Benutzer nicht anmelden.

Einstellungen im Überblick¶

Einstellung / Umgebungsvariable	Standard	Wirkung
`kcforms.auth.allow-fixed-login` / `KCFORMS_AUTH_ALLOW_FIXED_LOGIN`	`false`	erlaubt Fixed-Login
`kcforms.auth.emergency` / `KCFORMS_AUTH_EMERGENCY`	`false`	Notfall-Modus
`kcforms.auth.emergency-user` / `KCFORMS_AUTH_EMERGENCY_USER`	`admin`	Notfall-Konto
`kcforms.auth.emergency-password` / `KCFORMS_AUTH_EMERGENCY_PASSWORD`	`admin`	Notfall-Passwort
`kcforms.security.login-throttle.max-per-user` / `KCFORMS_SECURITY_LOGIN_THROTTLE_MAX_PER_USER`	`5`	Fehlversuche je Name bis zur Sperre
`kcforms.security.login-throttle.max-per-ip` / `KCFORMS_SECURITY_LOGIN_THROTTLE_MAX_PER_IP`	`30`	Fehlversuche je Absender-Adresse bis zur Sperre
`kcforms.security.login-throttle.block-minutes` / `KCFORMS_SECURITY_LOGIN_THROTTLE_BLOCK_MINUTES`	`15`	Dauer der Sperre und des Zählfensters (Minuten)

Audit-Protokoll¶

Jeder Anmeldeversuch — erfolgreich oder nicht, auch jeder Test-Login — schreibt einen Eintrag in audit_event:

Spalte	Inhalt
`ts`	Zeitpunkt
`actor`	Anmeldename
`kind`	`auth.login.success` bzw. `auth.login.failure`
`detail`	Strategie und ggf. Fehlercode, z. B. `strategy=scriptLogin reason=invalid_credentials`

So lässt sich nachvollziehen, über welche Strategie sich jemand angemeldet hat und warum ein Versuch scheiterte.

Anmeldung¶

DB-Login¶

Fixed-Login — nur für die Entwicklung¶

Skript-Login — eigene Logik in JavaScript¶

Test-Login¶