Zum Hauptinhalt springen

Übersicht

protocol: saml macht das Gateway zu einem SAML-2.0-Service-Provider statt zu einem OIDC-Client. Sessions, User-Paths, Gruppen-Mapping, Abmeldung und Anmeldeereignisse funktionieren genau wie für OIDC SSO beschrieben; es ändert sich nur, wie eine Anmeldung nachgewiesen wird.
  • Ein Protokoll und ein Identity-Provider pro Gateway. Mit protocol: saml dürfen die OIDC-Client-Einstellungen (issuer_url, client_id, client_secret, redirect_url) nicht gesetzt sein, weder in YAML noch in der Umgebung. Mit protocol: oidc darf keine saml-Einstellung gesetzt sein. Andernfalls wird der Start abgebrochen.
  • Ein Protokollwechsel ändert jede Principal-ID. Die in Request-Log-Einträgen gespeicherte ID wird aus dem Protokoll, dem Identity-Provider und dem Subject abgeleitet. Dieselbe Person erscheint nach dem Wechsel also unter einem neuen Principal.
SAML benötigt zusätzlich zu sso das saml-Entitlement. Wie jede aktivierte SSO-Konfiguration schlägt es geschlossen fehl (fail closed): Der Start wird abgebrochen, wenn eines der Entitlements fehlt oder die Konfiguration ungültig ist. Das Gateway fällt nie auf OIDC oder auf ein ungeschütztes Dashboard zurück.

SAML konfigurieren

Dieselbe Einrichtung mit Umgebungsvariablen, die die YAML-Werte überschreiben:
Die gemeinsamen Einstellungen unter Identität und Zulassung behalten ihre Bedeutung.

Gateway registrieren

Das Gateway stellt zwei URLs bereit, beide unterhalb eines ggf. konfigurierten BASE_PATH:
1

SAML-2.0-Anwendung beim Identity-Provider anlegen

Importieren Sie die URL der Service-Provider-Metadaten, wenn der Provider das unterstützt und das Gateway bereits läuft. Andernfalls tragen Sie die ACS-URL mit HTTP-POST-Binding und die Entity-ID (Audience) von Hand ein.
2

Assertion signieren

Die Assertion selbst muss mit RSA-SHA256 oder stärker und einem RSA-Schlüssel von mindestens 2048 Bit signiert sein. Nur die Response zu signieren genügt nicht. Verschlüsseln Sie die Assertion nicht. Das Gateway sendet unsignierte Requests über HTTP-Redirect.
3

Stabiles Subject und die verwendeten Attribute senden

Verwenden Sie eine persistente NameID, oder senden Sie eine unveränderliche Benutzer-ID als Attribut und nennen Sie es in principal_attribute. Geben Sie das Attribut für den User-Path frei und, falls Sie admin_groups oder Gruppen-Mappings verwenden, das Gruppen-Attribut mit nur den Gruppen, die das Gateway benötigt.
4

Dem Gateway die Metadaten des Identity-Providers geben

Setzen Sie idp_metadata_url, oder laden Sie die Metadaten herunter und setzen Sie idp_metadata_file. Die Metadaten müssen genau einen Identity-Provider mit einem HTTP-Redirect-Anmeldeendpunkt und mindestens einem Signaturzertifikat beschreiben.
5

Gateway starten und anmelden

Öffnen Sie /sso/login unterhalb eines ggf. konfigurierten BASE_PATH. Schlägt die Anmeldung fehl, schlagen Sie den Grund unter Gründe für abgelehnte Anmeldungen nach.
Diese Schritte verwenden allgemeine SAML-2.0-Begriffe; die Namen der Einstellungen unterscheiden sich je nach Identity-Provider. Die SAML-Anmeldung wurde bisher nur gegen einen Test-Identity-Provider verifiziert. Behandeln Sie die erste Einführung mit Ihrem Provider daher als Integration, die zu testen ist, und nicht als erprobtes Rezept.

Attribute und Principal

user_path_claim und groups_claim benennen SAML-Attribute, entweder direkt über den Name des Attributs oder über einen Alias in saml.attributes:
  • Ein Alias verdeckt ein SAML-Attribut gleichen Namens.
  • Das User-Path-Attribut muss genau einen Wert haben; umgebende Leerzeichen werden entfernt. Gruppenwerte werden nicht beschnitten und exakt so verglichen, wie sie gesendet werden. Ein Gruppen-Attribut mit einem einzelnen leeren Wert bedeutet keine Gruppen, und eines mit einem Nicht-Text-Wert lehnt die Anmeldung mit claim_mapping_failed ab, solange admin_groups oder Gruppen-Mappings gesetzt sind.
  • Eine Assertion ohne das Gruppen-Attribut, die stattdessen http://schemas.microsoft.com/claims/groups.link von Entra ID trägt (gesendet für Personen in mehr als 150 Gruppen), wird mit groups_overage abgelehnt, solange admin_groups oder Gruppen-Mappings gesetzt sind. Siehe Grenzen.
  • Eine Änderung von protocol oder des Attributs, auf das user_path_claim oder groups_claim über saml.attributes verweist, beendet bestehende Sessions, wie unter Wenn sich die Konfiguration ändert beschrieben.
  • allowed_domains und der Standard user_path_claim: email lesen das Attribut, das email heißt oder diesen Alias trägt. Der User-Path wird nur bei user_path_claim: email oder user_path_case_insensitive: true in Kleinbuchstaben umgewandelt.
  • Der Principal ist die NameID oder, falls gesetzt, principal_attribute. Eine transiente NameID ändert sich bei jeder Anmeldung und wird abgelehnt, sofern principal_attribute nicht gesetzt ist.

E-Mail-Vertrauen

trust_email entscheidet, ob das E-Mail-Attribut als verifizierte E-Mail-Adresse gilt. Der Standardwert ist false, weil SAML kein Gegenstück zu email_verified von OIDC kennt: Eine Signatur belegt, dass der Identity-Provider die Adresse gesendet hat, nicht, dass er sie geprüft hat. Der User-Path ist zugleich der Zugriffsbereich der Session. Können Personen ihre eigene E-Mail-Adresse beim Identity-Provider ändern, könnte jemand die Adresse einer Kollegin oder eines Kollegen eintragen und sich auf deren Pfad anmelden. Ohne trust_email lehnt der Start eine Konfiguration ab, die von der E-Mail-Adresse abhängt:
  • einen user_path_claim, der sie liest, einschließlich des Standards user_path_claim: email;
  • allowed_domains;
  • einen groups_claim, der sie liest, wenn admin_groups oder Gruppen-Mappings gesetzt sind.
Wählen Sie daher eine der folgenden Möglichkeiten:
Die Prüfung beim Start erkennt nur Namen: email, das Attribut mit dem Alias email und die bekannten E-Mail-Attribute http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, http://schemas.xmlsoap.org/claims/EmailAddress, mail, email, EmailAddress, User.Email, urn:oid:0.9.2342.19200300.100.1.3 und urn:oid:1.2.840.113549.1.9.1, alle ohne Beachtung der Groß- und Kleinschreibung, direkt oder über einen Alias. Ein Attribut, das eine E-Mail-Adresse oder einen anderen von Personen änderbaren Wert unter einem anderen Namen trägt, besteht die Prüfung. Verwenden Sie für user_path_claim oder groups_claim niemals ein Attribut, das ein Benutzer ändern kann.

Was bei jeder Response geprüft wird

Eine Anmeldung gelingt nur, wenn alle folgenden Punkte zutreffen. Jeder Fehlschlag hat seinen eigenen Ablehnungsgrund.
  • Sie beantwortet eine Anmeldung, die dieser Browser gestartet hat. Das signierte Transaktions-Cookie (10 Minuten gültig), RelayState und InResponseTo müssen übereinstimmen.
  • Sie ist an dieses Gateway adressiert. Destination und Recipient entsprechen acs_url, und die Audience ist die Entity-ID des Gateways.
  • Sie stammt vom konfigurierten Identity-Provider. Der Issuer ist die Entity-ID aus den Metadaten.
  • Die Assertion selbst ist signiert, und zwar mit einem aktuell gültigen Signaturzertifikat aus den Metadaten, mit RSA-SHA256 oder stärker und einem Schlüssel von mindestens 2048 Bit. Trägt das KeyInfo der Signatur ein Zertifikat, muss es dieses sein; eine Signatur ohne KeyInfo wird gegen jedes vertrauenswürdige Zertifikat geprüft, wie bei einem Zertifikatswechsel.
  • Es gibt genau eine Assertion, und sie ist nicht verschlüsselt.
  • Sie liegt innerhalb ihres Gültigkeitsfensters, bei 60 Sekunden zulässiger Uhrenabweichung.
  • Der Identity-Provider meldet Erfolg.
  • Sie nennt ein stabiles Subject: eine nicht transiente NameID oder principal_attribute.
  • Sie wurde noch nicht verwendet. Siehe Replay-Schutz.
  • Sie ist klein und einfaches XML: ein Formular von höchstens 1 MiB, höchstens 900 XML-Elemente, keine DTD, keine Kommentare und keine Processing Instructions.
Jeder Wert der Assertion, den eine Anmeldung verwendet (das Subject, die Attribute und die Conditions wie Audience und Gültigkeitsfenster), wird aus der Assertion so gelesen, wie ihre Signatur sie verifiziert hat, nie aus dem Rest des Dokuments. Einige Prüfungen vergleichen Werte außerhalb der Signatur der Assertion mit dem, was das Gateway erwartet: RelayState ist ein Feld des gesendeten Formulars, und Destination, InResponseTo, Issuer und Status der Response gehören zum Umschlag der Response, den eine Signatur nur abdeckt, wenn der Identity-Provider auch die Response signiert. Keiner dieser Werte dient als Identität. Danach gilt die Zulassung wie bei OIDC.

Metadaten des Identity-Providers

Aus einer Datei. Die Datei wird einmal gelesen. Eine nicht lesbare oder ungültige Datei bricht den Start ab. Nachdem der Identity-Provider sein Signaturzertifikat rotiert hat, müssen Sie die Datei ersetzen und das Gateway neu starten. Von einer URL. Das Gateway ruft die Metadaten beim Start und danach alle metadata_refresh_interval ab. Eine dort veröffentlichte Zertifikatsrotation wird also ohne Neustart übernommen. Eine fehlgeschlagene Aktualisierung behält die letzten gültigen Metadaten. Ist die URL beim Start nicht erreichbar, startet das Gateway trotzdem, Anmeldungen antworten mit 503 und identity_provider_unavailable, und der Abruf wird im Hintergrund wiederholt (5 Sekunden, verdoppelt bis 5 Minuten). Setzen Sie require_discovery: true (PRO_SSO_REQUIRE_DISCOVERY=true), um daraus stattdessen einen Startfehler zu machen. Metadaten aus beiden Quellen werden nach ihrem validUntil nicht mehr verwendet; Anmeldungen sind dann nicht möglich, bis neuere Metadaten geladen sind.

Was eine Aktualisierung ändern darf

Eine Aktualisierung darf die Signaturzertifikate, die Anmelde-URL und validUntil ersetzen. Die Entity-ID des Identity-Providers darf sie nicht ändern: Solche Metadaten werden abgelehnt, die aktuellen Metadaten bleiben in Gebrauch, und ein Fehler wird protokolliert. Starten Sie das Gateway neu, um zu einer anderen Entity-ID zu wechseln. Wer die Metadaten-URL kontrolliert, kann ein eigenes Signaturzertifikat veröffentlichen. Jede Aktualisierung, die die vertrauenswürdigen Zertifikate ändert, wird daher auf Warnstufe protokolliert, mit den SHA-256-Fingerprints in added_fingerprints und removed_fingerprints:
Richten Sie einen Alarm auf diese Zeile ein. Beim Start werden die Fingerprints protokolliert, denen das Gateway vertraut.

Zertifikat-Pinning

Damit eine Rotation nicht automatisch akzeptiert wird, listen Sie die SHA-256-Fingerprints der Signaturzertifikate des Identity-Providers auf:
Fingerprints sind hexadezimal, unabhängig von Groß- und Kleinschreibung, mit optionalen Doppelpunkten. Nur aufgelisteten Zertifikaten wird vertraut, bei einer Metadaten-Datei ebenso wie bei einer URL. Metadaten ohne eines dieser Zertifikate brechen den Start ab; bei einer Aktualisierung werden sie abgelehnt, und die letzten gültigen Metadaten bleiben in Gebrauch. Zum Rotieren fügen Sie den neuen Fingerprint hinzu, bevor der Identity-Provider wechselt, und entfernen den alten danach. Jeder Schritt erfordert einen Neustart.

Sessions und Abmeldung

Eine Session endet nach session_ttl oder zum SessionNotOnOrAfter der Assertion, wenn dieser Zeitpunkt früher liegt. Eine Assertion, deren SessionNotOnOrAfter bereits überschritten ist, wird abgelehnt. Die Abmeldung beendet die GoModel-Session und leitet danach zu provider_logout_url weiter, wenn diese gesetzt ist, wie bei OIDC; siehe Abmeldung über Replicas hinweg.

Replay-Schutz

Jede Assertion wird genau einmal akzeptiert. Das Gateway merkt sich die IDs verwendeter Assertions, bis sie ablaufen, im Arbeitsspeicher und im konfigurierten Storage-Backend.
  • PostgreSQL oder MongoDB: Eine erneut gesendete Assertion wird auf jeder Replica abgelehnt, die den Storage teilt. Zwei Replicas, die dieselbe Assertion im selben Augenblick erhalten, könnten sie beide akzeptieren; dafür wird zusätzlich das Transaktions-Cookie der Person benötigt.
  • SQLite (Standard): Der Schutz gilt pro Instanz. Betreiben Sie wie bei der Abmeldung nur eine Replica; das Gateway protokolliert beim Start eine Warnung.
  • Storage nicht verfügbar: Die Anmeldung wird mit replay_check_unavailable abgelehnt.

Grenzen

  • Etwa 850 Gruppen pro Person. Jeder Gruppenwert ist ein XML-Element, und eine Response mit mehr als 900 Elementen wird mit too_many_elements abgelehnt. Die Grenze ist nicht konfigurierbar. Filtern Sie beim Identity-Provider: Senden Sie nur die Gruppen, die der Anwendung zugewiesen sind oder die in admin_groups und group_mappings genannt werden.
  • Entra ID: höchstens 150 Gruppen in einer Assertion. Darüber sendet Entra ID statt der Gruppen http://schemas.microsoft.com/claims/groups.link, und solange admin_groups oder Gruppen-Mappings gesetzt sind, wird die Anmeldung mit groups_overage abgelehnt. Senden Sie nur die Gruppen, die der Anwendung zugewiesen sind.
  • Keine beim Identity-Provider gestartete Anmeldung. Anmeldungen müssen am Gateway beginnen (/sso/login unterhalb eines ggf. konfigurierten BASE_PATH). Unaufgeforderte Responses werden abgelehnt.
  • Keine verschlüsselten Assertions. Sie werden mit encrypted_assertion abgelehnt.
  • Kein SAML Single Logout. Das Gateway sendet keine SAML-Logout-Requests und verarbeitet keine des Identity-Providers. Die Abmeldung beendet die GoModel-Session; die Session beim Identity-Provider endet nur über eine Weiterleitung zu provider_logout_url.
  • Ein Identity-Provider pro Gateway.
Zuletzt geändert am 18. November 2026