SAML-Anmeldung (Hochschul-Login)¶

Administration → Benutzer & Zugang → SAML 2.0 (Hochschul-Login)

Mit SAML melden sich Personen mit dem Konto ihrer Hochschule an. Sie brauchen kein eigenes Passwort für KCForms. Sie klicken auf einen Knopf. Die Hochschule fragt nach Name und Passwort. Danach sind sie in KCForms angemeldet.

Diese Seite erklärt jeden Schritt. Sie brauchen dafür kein Fachwissen über SAML.

Die wichtigsten Wörter¶

Wort	Bedeutung
IdP (Identity Provider)	Der Anmeldedienst der Hochschule. Dort steht das Passwort.
SP (Service Provider)	Der Dienst, bei dem man sich anmelden will. Hier: KCForms.
Föderation	Ein Verbund von Hochschulen und Diensten. Er sorgt dafür, dass sich alle gegenseitig vertrauen. In Schweden heißt er SWAMID, in Deutschland DFN-AAI, weltweit eduGAIN.
Metadaten	Eine XML-Datei mit dem „Ausweis“ eines Dienstes: Adressen und Schlüssel. Die Hochschule und KCForms tauschen ihre Metadaten aus.
Entity-ID	Der eindeutige Name eines Dienstes. Er sieht aus wie eine Web-Adresse.
Attribut	Eine Angabe über die Person, z. B. Name, E-Mail oder „ist Mitarbeiterin“.
Entity-Kategorie	Ein Etikett in den Metadaten. Es sagt der Hochschule, welche Attribute sie schicken darf.

So läuft eine Anmeldung ab¶

sequenceDiagram
    actor P as Person
    participant K as KCForms
    participant H as Hochschule (IdP)
    P->>K: Klick auf „Mit Hochschul-Konto anmelden“
    K->>H: Bitte melde diese Person an (signiert)
    H->>P: Anmeldeseite der Hochschule
    P->>H: Name + Passwort (+ zweiter Faktor)
    H->>K: Antwort mit Attributen (signiert und verschlüsselt)
    K->>K: Prüfen: Signatur, Zeit, Empfänger, Hochschule
    K->>P: Angemeldet

KCForms prüft jede Antwort genau:

Ist sie von der richtigen Hochschule signiert?
Ist sie frisch (höchstens 5 Minuten Uhr-Abweichung)?
Ist sie für KCForms bestimmt?
Gehört die Kennung zu dieser Hochschule? Eine Kennung wie anna@uni.se wird nur von der Hochschule mit dem Bereich uni.se angenommen.

Bevor Sie anfangen¶

Sie brauchen:

Eine Adresse für KCForms mit https://, z. B. https://formulare.uni.se. Föderationen nehmen keine Adresse mit http:// an.
Eine Ansprechperson in der IT der Hochschule.
Die Adresse einer Datenschutzerklärung und einer Info-Seite zu KCForms. Föderationen verlangen beides.
Zwei E-Mail-Adressen: eine für Technik und eine für Verwaltung. Am besten Funktions-Adressen, z. B. it-support@uni.se.

Schritt 1: Einschalten¶

Öffnen Sie Administration → SAML 2.0 (Hochschul-Login).
Setzen Sie den Haken SAML eingeschaltet.
Tragen Sie bei Adresse von KCForms die https-Adresse ein. Ohne Pfad am Ende.
Klicken Sie auf Speichern.

Beim ersten Speichern erzeugt KCForms einen eigenen Schlüssel. Er ist 3 Jahre gültig. Der geheime Teil verlässt den Server nie.

Schritt 2: Die Hochschule eintragen¶

KCForms braucht die Metadaten der Hochschule. Es gibt drei Fälle.

Schweden (SWAMID)Deutschland (DFN-AAI)Direkt bei der Hochschule

Fragen Sie die IT nach der Entity-ID ihres Anmeldedienstes. Beispiel: https://idp.uni.se/idp/shibboleth.
Tragen Sie bei Metadaten der Hochschule (Adresse) ein: https://mds.swamid.se/entities/ und dahinter die Entity-ID in URL-Schreibweise. Beispiel für die KTH: https://mds.swamid.se/entities/https%3A%2F%2Fsaml.sys.kth.se%2Fidp%2Fshibboleth
Laden Sie das Zertifikat von SWAMID: https://mds.swamid.se/md/md-signer2.crt. Öffnen Sie die Datei mit einem Texteditor. Kopieren Sie den ganzen Text in das Feld Zertifikat der Föderation.
Prüfen Sie den Fingerabdruck. Er muss so beginnen: A6:78:5A:37:C9:C9.

Tragen Sie bei Metadaten der Hochschule (Adresse) die Sammel-Datei ein: https://www.aai.dfn.de/metadata/dfn-aai-idp-metadata.xml.
Tragen Sie bei Entity-ID der Hochschule den Namen des Anmeldedienstes ein. Die IT der Hochschule nennt ihn.
Laden Sie das Zertifikat des DFN: https://www.aai.dfn.de/metadata/dfn-aai.pem. Kopieren Sie den Text in das Feld Zertifikat der Föderation.

Manche Hochschulen sind in keiner Föderation, oder sie benutzen z. B. Microsoft Entra ID.

Die IT gibt Ihnen eine Adresse für die Metadaten oder eine XML-Datei.
Tragen Sie die Adresse ein. Oder kopieren Sie den Inhalt der Datei in das Feld Metadaten als XML einfügen.
Das Feld Zertifikat der Föderation bleibt leer. Dann muss die Adresse mit https:// beginnen.
Fehlen in den Metadaten die Angaben zum Geltungsbereich (bei Entra ID und Keycloak üblich), tragen Sie unter Weitere Attribute und Geltungsbereich → Zusätzlich erlaubte Geltungsbereiche die Domain der Hochschule ein, z. B. uni.se.

Klicken Sie danach auf Speichern und dann auf Selbsttest. Der Selbsttest lädt die Metadaten und prüft sie. Er zeigt den Namen der Hochschule und ihre Geltungsbereiche.

Föderations-Metadaten nie ohne Zertifikat

Bei SWAMID und DFN-AAI ist das Zertifikat Pflicht. Ohne Zertifikat prüft KCForms die Signatur nicht. Dann könnte jemand gefälschte Metadaten unterschieben. KCForms lehnt auch Metadaten ab, die abgelaufen sind oder kein Ablaufdatum haben.

Schritt 3: KCForms bei der Hochschule bekannt machen¶

Unter 2. Das geben Sie der Hochschule bzw. der Föderation steht eine Adresse. Sie endet auf /api/auth/saml/metadata. Das ist der Ausweis von KCForms. Darin steht alles, was die Hochschule braucht.

Füllen Sie vorher den Bereich 4. Angaben über KCForms aus. Unter der Adresse sehen Sie, was noch fehlt (rot) und was ein Tipp ist (gelb).

Schweden (SWAMID)Deutschland (DFN-AAI)Direkt bei der Hochschule

Öffnen Sie https://metadata.swamid.se/. Melden Sie sich mit Ihrem Hochschul-Konto oder mit eduID an.
Laden Sie die Metadaten von KCForms hoch (Knopf Metadaten herunterladen in KCForms).
Bitten Sie um Veröffentlichung.
Leiten Sie die Bestätigungs-Mail an SWAMID Operations weiter. Schreiben Sie dazu, mit welcher Hochschule es einen Vertrag gibt.
Einmal im Jahr bestätigen Sie, dass die Angaben noch stimmen. Sonst wird der Eintrag gelöscht.

Danach muss die Hochschule die Attribute freigeben. Mit der Entity-Kategorie Personalized geht das bei den meisten schwedischen Hochschulen von selbst.

Die Hochschule (oder Sie mit einem DFN-Vertrag) trägt KCForms in der DFN-AAI-Verwaltung ein.
Zuerst kommt KCForms in die Test-Föderation. Nach einem Funktionstest wechselt es in den Betrieb.
Der DFN verlangt einen Sicherheits-Kontakt. Tragen Sie ihn mit Namen ein: Security Team <security@uni.de>.

Geben Sie der IT die Adresse der Metadaten. Sie trägt KCForms in ihrem Anmeldedienst ein. Schicken Sie der IT auch den Abschnitt Für die IT der Hochschule.

Schritt 4: Testen¶

Testen Sie, bevor Sie SAML für alle freischalten.

Klicken Sie auf Test-Anmeldung …. Ein neues Fenster öffnet sich.
Melden Sie sich mit einem Konto der Hochschule an.
Sie sehen eine Seite Ergebnis der SAML-Test-Anmeldung.

Die Seite zeigt:

ob die Anmeldung funktionieren würde,
welches KCForms-Konto die Person bekäme,
welche Gruppen sie hätte,
alle Attribute, die die Hochschule geschickt hat.

Beim Test wird nichts gespeichert. Es entsteht kein Konto. Sie bleiben als Admin angemeldet.

Keine Attribute in der Tabelle?

Dann hat die Hochschule die Attribute noch nicht freigegeben. Schicken Sie der IT das Bild der Test-Seite. Meist fehlt die Freigabe für KCForms oder die Entity-Kategorie.

Schritt 5: Wer bekommt welches Konto?¶

Das Konto finden¶

KCForms sucht das Konto über eine Kennung der Hochschule. Die Vorgabe ist:

subject-id — eine Kennung, die sich nie ändert.
Wenn die fehlt: eduPersonPrincipalName, z. B. anna@uni.se.

Diese Kennung ist der Loginname in KCForms. Sie können stattdessen auch über die E-Mail-Adresse oder die schwedische Personnummer suchen lassen.

Neue Personen¶

Ist der Haken Unbekannte Personen automatisch als neues Konto anlegen gesetzt, legt KCForms bei der ersten Anmeldung ein Konto an. Ohne Haken bekommen unbekannte Personen eine Meldung. Dann legt ein Admin das Konto vorher an — mit der Kennung als Loginname.

Ein Konto aus SAML hat kein Passwort. Man kann sich damit nur über die Hochschule anmelden.

Gruppen aus der Hochschule¶

Die Hochschule schickt, was eine Person ist: staff (Personal), faculty (Lehrende), student (Studierende) und andere. Sie können das auf Gruppen in KCForms abbilden.

Eine Zeile je Wert:

staff   = MITARBEITENDE
faculty = MITARBEITENDE, LEHRENDE
student = STUDIERENDE

Die Gruppen müssen in KCForms schon existieren.

So wirkt die Tabelle bei jeder Anmeldung:

Gruppen, die in der Tabelle stehen, setzt KCForms nach den Angaben der Hochschule. Ist jemand nicht mehr student, verliert er die Gruppe STUDIERENDE.
Gruppen, die nicht in der Tabelle stehen, bleiben, wie sie sind. Was ein Admin von Hand vergibt, bleibt also erhalten.

Passwort-Anmeldung daneben¶

Der Haken Anmeldung mit Passwort zusätzlich erlauben ist gesetzt. Dann sehen Personen auf der Anmeldeseite beides: den Hochschul-Knopf und das Passwort-Feld. Das ist wichtig für Admin-Konten und Dienstkonten. Nehmen Sie den Haken nur weg, wenn wirklich alle über die Hochschule kommen.

Passwort-Anmeldung über LDAP¶

Neben SAML läuft die Passwort-Anmeldung normalerweise über die Benutzerverwaltung von KCForms. Stehen die Admin- oder Dienstkonten in einem LDAP-Verzeichnis, wählen Sie bei Passwort-Anmeldung prüfen über den Eintrag Login-Skript. Dann prüft das Login-Skript, das unter Administration → Anmeldung aktiv ist, das Passwort — siehe Anmeldung.

Eigene Regeln: das Zuordnungs-Skript¶

Die Einstellungen in Schritt 5 decken die meisten Fälle ab. Für alles andere gibt es das Zuordnungs-Skript (Bereich 3b). Das ist ein kurzes JavaScript.

Mit dem Skript können Sie:

Personen ablehnen, z. B. alle außer Mitarbeitenden,
ein anderes Konto wählen, z. B. ein gemeinsames Gastkonto,
Gruppen dazugeben, wegnehmen oder ganz festlegen.

Wann das Skript läuft¶

flowchart LR
    A[Antwort der Hochschule] --> B{Sicherheit:<br/>Signatur, Zeit,<br/>Geltungsbereich}
    B -- nicht in Ordnung --> X[Abgelehnt]
    B -- in Ordnung --> C[Vorschlag aus den<br/>Einstellungen]
    C --> D[Zuordnungs-Skript]
    D --> E{Konto gesperrt?<br/>Anlegen erlaubt?}
    E --> F[Angemeldet]

Das Skript läuft nach den Sicherheitsprüfungen. Es kann eine gefälschte oder fremde Anmeldung also nicht durchlassen. Es entscheidet nur, welches Konto eine echte Person bekommt.

Auch danach prüft KCForms weiter: Ein gesperrtes Konto bleibt gesperrt. Ein neues Konto entsteht nur, wenn Unbekannte Personen automatisch anlegen eingeschaltet ist.

Die wichtigsten Befehle¶

Befehl	Was er tut
`saml.has("eduPersonScopedAffiliation", "staff")`	Hat die Person diesen Wert? `"staff"` trifft auch `"staff@uni.se"`.
`saml.attr("mail")`	Der erste Wert eines Attributs, z. B. die E-Mail.
`saml.values("eduPersonScopedAffiliation")`	Alle Werte eines Attributs.
`saml.login`	Das vorgeschlagene Konto. Eine Zuweisung wählt ein anderes.
`saml.groups()`	Die vorgeschlagenen Gruppen.
`saml.addGroup("G")` / `saml.removeGroup("G")`	Eine Gruppe dazugeben / wegnehmen.
`saml.setGroups(["A", "B"])`	Genau diese Gruppen — auch von Hand vergebene fallen weg.
`saml.proposalError`	Warum der Vorschlag nicht geht, z. B. `"saml_unknown_user"`. Sonst `null`.
`saml.test`	`true` in der Test-Anmeldung.
`auth.fail("code", "Text")`	Ablehnen. Der Text steht auf der Anmeldeseite.

Attribute dürfen Sie mit dem kurzen Namen (mail) oder dem langen (urn:oid:0.9.2342.19200300.100.1.3) ansprechen. Außerdem gibt es db, log, kc und ldap — wie im Login-Skript.

Drei Regeln:

Nichts tun heißt annehmen. Ein Skript ohne Entscheidung lässt den Vorschlag gelten.
Ein Fehler im Skript heißt ablehnen. Ein kaputtes Skript lässt niemanden durch, den es eigentlich abweisen sollte.
Nach 5 Sekunden bricht KCForms das Skript ab.

Beispiel A: nur Mitarbeitende¶

Studierende sehen auf der Anmeldeseite den Text aus dem Skript.

if (!saml.has("eduPersonScopedAffiliation", "staff")) {
  auth.fail("nur_personal", "KCForms ist nur für Mitarbeitende freigegeben.");
}

Beispiel B: Lehrende bekommen eine zusätzliche Gruppe¶

if (saml.has("eduPersonScopedAffiliation", "faculty")) {
  saml.addGroup("LEHRENDE");
}

Beispiel C: Gäste teilen sich ein Gastkonto¶

Ohne Skript würden Gäste abgewiesen, weil sie kein Konto haben. Das Skript gibt ihnen das gemeinsame Konto gast.

if (saml.proposalError === "saml_unknown_user"
    && saml.has("eduPersonScopedAffiliation", "affiliate")) {
  saml.login = "gast";
}

Beispiel D: Gruppen ganz festlegen und protokollieren¶

if (saml.has("eduPersonScopedAffiliation", "student")) {
  saml.setGroups(["STUDIERENDE"]);
}
log.info("SAML " + saml.attr("mail") + " -> " + saml.login + " " + saml.groups().join(","));

Die Beispiele A bis D laufen bei jedem Test von KCForms in echtem JavaScript mit (SamlMappingScriptTest).

Das Skript ist ein Admin-Werkzeug

Ein Skript kann jede Person auf jedes Konto lenken — auch auf ein Admin-Konto. Deshalb dürfen es nur Administratoren bearbeiten. Prüfen Sie jede Änderung mit der Test-Anmeldung, bevor sie gilt.

Test-Anmeldung und Skripte, die etwas schreiben

Die Test-Anmeldung führt das Skript mit aus. Schreibt Ihr Skript selbst etwas (z. B. mit db), fragen Sie vorher if (!saml.test) { … } ab.

Schritt 6: Für alle freischalten¶

Öffnen Sie Administration → Anmeldung.
Wählen Sie die Anmeldeart SAML 2.0.
Speichern.

Ab jetzt sehen alle auf der Anmeldeseite den Knopf Mit Hochschul-Konto anmelden. Wer über einen Link zu einem Formular kommt, landet nach der Anmeldung wieder bei diesem Formular.

Meldungen auf der Anmeldeseite¶

Meldung (gekürzt)	Was ist passiert?	Was tun?
„… noch keinen Zugang zu KCForms“	Kein Konto mit dieser Kennung.	Konto anlegen oder „automatisch anlegen“ einschalten.
„… keine Kennung mitgeschickt“	Die Hochschule hat die Attribute nicht freigegeben.	IT bitten, subject-id oder eduPersonPrincipalName freizugeben.
„Die Kennung passt nicht zu dieser Hochschule“	Die Kennung endet auf eine fremde Domain.	Absicht: Schutz vor fremden Konten. Bei Keycloak/Entra den Geltungsbereich eintragen.
„… ist gesperrt“	Das KCForms-Konto ist deaktiviert.	In der Benutzerverwaltung prüfen.
„… zweiter Faktor nötig“	MFA ist verlangt, die Hochschule hat ohne angemeldet.	Person meldet sich mit zweitem Faktor an.
„… hat zu lange gedauert …“	Die Anmeldung dauerte über 10 Minuten oder lief in zwei Fenstern.	Noch einmal anmelden.
„Verbindung zur Hochschule gestört“	Die Metadaten lassen sich nicht laden.	Selbsttest öffnen, die Meldung dort zeigt den Grund.
Text aus Ihrem Zuordnungs-Skript	Das Skript hat abgelehnt (`auth.fail`).	Gewollt — oder das Skript prüfen.
„… Fehler in der Konfiguration …“	Das Zuordnungs-Skript ist abgebrochen.	Protokoll: `SAML-Zuordnungs-Skript fehlgeschlagen`.

Den genauen Grund schreibt KCForms in das Protokoll (SAML-Anmeldung abgelehnt [Code]: …).

Zweiten Faktor verlangen¶

Unter 5. Sicherheit → Anmeldung mit zweitem Faktor verlangen wählen Sie REFEDS MFA. Dann muss die Hochschule bestätigen, dass ein zweiter Faktor benutzt wurde. Fehlt die Bestätigung, lehnt KCForms ab.

Schlüssel wechseln¶

Der Schlüssel von KCForms ist 3 Jahre gültig. 90 Tage vor dem Ablauf zeigt die Admin-Seite eine Warnung.

So wechseln Sie ohne Unterbrechung:

Neuen Schlüssel vorbereiten. Er steht ab sofort zusätzlich in den Metadaten.
Warten, bis die Föderation die neuen Metadaten verteilt hat. Bei SWAMID ein paar Tage. Bei einer direkt angebundenen Hochschule: Die IT lädt die Metadaten neu.
Neuen Schlüssel aktiv schalten. Der alte entfällt.

Nicht „Sofort ersetzen“

Dieser Knopf tauscht den Schlüssel auf einmal. Bis die Hochschule die neuen Metadaten hat, kann sich niemand anmelden.

Für die IT der Hochschule¶

Angabe	Wert
Metadaten	`https://<KCForms>/api/auth/saml/metadata`
Entity-ID	wie die Metadaten-Adresse (sofern nicht anders eingestellt)
Antwort-Adresse (ACS)	`https://<KCForms>/api/auth/saml/acs`, Bindung HTTP-POST
Signatur	Antwort oder Assertion signiert (Pflicht)
Verschlüsselung	wird unterstützt und empfohlen
NameID	beliebig, z. B. `transient` — KCForms benutzt sie nicht
Kennung	`subject-id` (bevorzugt) oder `eduPersonPrincipalName`
Weitere Attribute	`mail`, `givenName`, `sn`, `displayName`, `eduPersonScopedAffiliation`
Entity-Kategorie	REFEDS Personalized Access (Vorgabe)
Single Logout	nicht unterstützt — Abmelden beendet nur die KCForms-Sitzung

Attribute bitte mit Namen in der Form urn:oid:… (SAML2-URI-Format), wie in SWAMID und DFN-AAI üblich.

Gut zu wissen¶

Abmelden beendet nur die Sitzung in KCForms. Bei der Hochschule bleibt man angemeldet, bis der Browser geschlossen wird. Auf geteilten Rechnern: Browser schließen.
Mehrere KCForms-Server hinter einem Lastverteiler: Eine Anmeldung muss auf demselben Server enden, auf dem sie begonnen hat („Sticky Sessions“). KCForms merkt sich laufende Anmeldungen im Speicher.
Metadaten lädt KCForms alle 4 Stunden neu. Ist die Hochschule kurz nicht erreichbar, bleibt der letzte gute Stand in Gebrauch — aber nie über sein Ablaufdatum hinaus.
Uhrzeit: Der Server muss die richtige Zeit haben (NTP). Mehr als 5 Minuten Abweichung führen zu abgelehnten Anmeldungen.
Eine Hochschule je Installation. Für Dienste mit Personen aus vielen Hochschulen gibt es Auswahl-Seiten (z. B. SeamlessAccess). Das ist in dieser Fassung nicht eingebaut.