Ü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: samldürfen die OIDC-Client-Einstellungen (issuer_url,client_id,client_secret,redirect_url) nicht gesetzt sein, weder in YAML noch in der Umgebung. Mitprotocol: oidcdarf keinesaml-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 konfigurieren
Die gemeinsamen Einstellungen unter
Identität und Zulassung behalten ihre
Bedeutung.
Gateway registrieren
Das Gateway stellt zwei URLs bereit, beide unterhalb eines ggf. konfiguriertenBASE_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_failedab, solangeadmin_groupsoder Gruppen-Mappings gesetzt sind. - Eine Assertion ohne das Gruppen-Attribut, die stattdessen
http://schemas.microsoft.com/claims/groups.linkvon Entra ID trägt (gesendet für Personen in mehr als 150 Gruppen), wird mitgroups_overageabgelehnt, solangeadmin_groupsoder Gruppen-Mappings gesetzt sind. Siehe Grenzen. - Eine Änderung von
protocoloder des Attributs, auf dasuser_path_claimodergroups_claimübersaml.attributesverweist, beendet bestehende Sessions, wie unter Wenn sich die Konfiguration ändert beschrieben. allowed_domainsund der Standarduser_path_claim: emaillesen das Attribut, dasemailheißt oder diesen Alias trägt. Der User-Path wird nur beiuser_path_claim: emailoderuser_path_case_insensitive: truein Kleinbuchstaben umgewandelt.- Der Principal ist die NameID oder, falls gesetzt,
principal_attribute. Eine transiente NameID ändert sich bei jeder Anmeldung und wird abgelehnt, sofernprincipal_attributenicht 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 Standardsuser_path_claim: email; allowed_domains;- einen
groups_claim, der sie liest, wennadmin_groupsoder Gruppen-Mappings gesetzt sind.
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),
RelayStateundInResponseTomüssen übereinstimmen. - Sie ist an dieses Gateway adressiert.
DestinationundRecipiententsprechenacs_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
KeyInfoder Signatur ein Zertifikat, muss es dieses sein; eine Signatur ohneKeyInfowird 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.
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 allemetadata_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 undvalidUntil 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:
Zertifikat-Pinning
Damit eine Rotation nicht automatisch akzeptiert wird, listen Sie die SHA-256-Fingerprints der Signaturzertifikate des Identity-Providers auf:Sessions und Abmeldung
Eine Session endet nachsession_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_unavailableabgelehnt.
Grenzen
- Etwa 850 Gruppen pro Person. Jeder Gruppenwert ist ein XML-Element, und
eine Response mit mehr als 900 Elementen wird mit
too_many_elementsabgelehnt. Die Grenze ist nicht konfigurierbar. Filtern Sie beim Identity-Provider: Senden Sie nur die Gruppen, die der Anwendung zugewiesen sind oder die inadmin_groupsundgroup_mappingsgenannt 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 solangeadmin_groupsoder Gruppen-Mappings gesetzt sind, wird die Anmeldung mitgroups_overageabgelehnt. Senden Sie nur die Gruppen, die der Anwendung zugewiesen sind. - Keine beim Identity-Provider gestartete Anmeldung. Anmeldungen müssen
am Gateway beginnen (
/sso/loginunterhalb eines ggf. konfiguriertenBASE_PATH). Unaufgeforderte Responses werden abgelehnt. - Keine verschlüsselten Assertions. Sie werden mit
encrypted_assertionabgelehnt. - 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.