SAML 2.0 ermöglicht Single Sign-on zwischen einem zentralen Identity Provider und einer oder mehreren Anwendungen.
Grundsätzlich existieren zwei Rollen:
| Rolle | Funktion |
|---|---|
| Identity Provider (IdP) | Authentifiziert den Benutzer und stellt eine SAML-Assertion aus |
| Service Provider (SP) | Anwendung, auf die der Benutzer zugreifen möchte |
Beispiele für einen Identity Provider:
Beispiele für Service Provider:
Grundaufbau:
Benutzer
│
▼
Identity Provider
│
│ SAML Response / Assertion
▼
Service Provider
Bei Verwendung eines zentralen Verzeichnisdienstes kann die Architektur beispielsweise so aussehen:
Active Directory / LDAP
│
▼
Identity Provider
│
│ SAML
▼
Anwendung
Eine Entity ID identifiziert einen SAML-Teilnehmer eindeutig.
Es existiert jeweils eine Entity ID für:
Identity Provider
Service Provider
Beispiel:
IdP Entity ID:
https://<IDP-FQDN>/application/saml/<APPLICATION_SLUG>/metadata/
SP Entity ID:
https://<SP-FQDN>
Die Entity ID ist ein Identifier und muss nicht zwingend eine tatsächlich
aufrufbare Webseite darstellen.
Der Issuer beschreibt den Absender einer SAML-Nachricht.
Bei einer AuthnRequest:
Issuer = Entity ID des Service Providers
Bei einer SAML Response bzw. Assertion:
Issuer = Entity ID des Identity Providers
Daher kann der Begriff Issuer je nach Konfigurationsoberfläche
unterschiedliche Werte erwarten.
Die Audience gibt an, für welchen Service Provider eine Assertion bestimmt ist.
In der Regel gilt:
Audience = SP Entity ID
Beispiel:
SP Entity ID:
https://<SP-FQDN>
Audience:
https://<SP-FQDN>
Einige Anwendungen verwenden einen eigenen Metadata-Pfad als Entity ID.
Beispiel:
https://<SP-FQDN>/apps/<APP>/saml/metadata
Die Audience muss dann genau diesem Wert entsprechen.
Die ACS-URL ist der Endpoint des Service Providers, an den der Identity Provider
die SAML Response zurücksendet.
Beispiel:
https://<SP-FQDN>/login/<AUTH_STRATEGY_ID>/callback
Die ACS-URL wird vom Service Provider vorgegeben.
Sie sollte nicht frei erfunden oder aus der Login-URL abgeleitet werden.
Der SSO Entry Point ist der Endpoint des Identity Providers, an den der
Service Provider seine AuthnRequest sendet.
Der korrekte Endpoint sollte aus den SAML-Metadaten des Identity Providers
übernommen werden.
Metadata:
https://<IDP-FQDN>/application/saml/<APPLICATION_SLUG>/metadata/
Dort befinden sich beispielsweise:
<SingleSignOnService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
Location="https://<IDP-FQDN>/<SSO-ENDPOINT>" />
Der jeweilige Location-Wert wird als SSO Entry Point verwendet.
SAML unterstützt unterschiedliche Transportmethoden.
Häufig verwendet werden:
HTTP-Redirect
HTTP-POST
Das konfigurierte Binding muss zum verwendeten SSO-Endpoint passen.
Beispiel:
Request Binding:
HTTP-Redirect
Entry Point:
<SingleSignOnService Location für HTTP-Redirect>
oder:
Request Binding:
HTTP-POST
Entry Point:
<SingleSignOnService Location für HTTP-POST>
Binding und Endpoint dürfen nicht vermischt werden.
Eine POST-Anfrage an einen Redirect-Endpoint oder umgekehrt kann beispielsweise
zu Fehlern wie:
403 Forbidden
CSRF verification failed
führen.
Der IdP-Metadata-Endpunkt ist daher die maßgebliche Quelle für die verfügbaren
Bindings und Endpoints.
Die wichtigste Entscheidung einer SAML-Integration ist die Frage:
Welcher Wert identifiziert einen Benutzer dauerhaft?
Mögliche Identifier sind beispielsweise:
sAMAccountName
username
UPN
E-Mail-Adresse
LDAP UUID
objectGUID
interne Benutzer-ID
Diese Werte sind nicht automatisch gleichbedeutend.
Die Unique ID sollte einen Benutzer innerhalb der Anwendung eindeutig und
möglichst dauerhaft identifizieren.
Beispiel bei Active Directory:
AD sAMAccountName
↓
IdP username
↓
SAML username Claim
↓
Service Provider Unique ID
Beispiel für einen SAML-Claim:
http://schemas.<IDP>/saml/username
Wenn eine Anwendung bereits direkt gegen LDAP oder Active Directory
authentifiziert, darf der SAML-Identifier nicht beliebig gewählt werden.
Zuerst muss geprüft werden:
Welchen Identifier verwendet die Anwendung bereits für den bestehenden Benutzer?
Beispiel:
LDAP Unique Identifier:
sAMAccountName
Dann sollte auch der SAML-Identifier denselben fachlichen Wert liefern:
AD sAMAccountName
→ IdP username
→ SAML username
→ Anwendung Unique ID
Dadurch wird vermieden, dass dieselbe Person unter unterschiedlichen
technischen Identitäten erscheint.
Auch wenn LDAP und SAML denselben Unique Identifier verwenden, bedeutet dies
nicht automatisch, dass eine Anwendung beide Anmeldeverfahren demselben
Benutzerkonto zuordnet.
Einige Anwendungen speichern zusätzlich die Authentifizierungsstrategie:
Benutzer
+ LDAP Provider
bzw.
Benutzer
+ SAML Provider
In diesem Fall können trotz identischer:
E-Mail-Adresse
Benutzername
Unique ID
zwei Benutzerkonten entstehen.
Vor parallelem Betrieb von LDAP und SAML muss deshalb geprüft werden, ob die
Anwendung mehrere Authentifizierungsprovider mit einem Benutzerkonto
verknüpfen kann.
Die SAML NameID ist ein Identifikationswert innerhalb der Assertion.
Mögliche Formate sind beispielsweise:
unspecified
persistent
transient
emailAddress
Die NameID ist nicht zwangsläufig dasselbe wie der Unique-ID-Claim der
Anwendung.
Beispielsweise kann eine Assertion enthalten:
NameID:
user01
username Claim:
user01
email Claim:
user01@example.invalid
Für eine konsistente Umgebung kann es sinnvoll sein, dass NameID und
Unique-ID-Claim denselben fachlichen Identifier enthalten.
Wenn sAMAccountName als zentraler Benutzer-Identifier verwendet wird:
AD sAMAccountName
→ IdP username
→ SAML NameID
→ SAML username Claim
→ Anwendung Unique ID
Das NameID-Format sollte dabei zum Inhalt passen.
Wird ein Benutzername übertragen, sollte nicht ohne Grund:
emailAddress
als Format verwendet werden.
Typische SAML Attribute sind:
Username
E-Mail-Adresse
Display Name
Vorname
Nachname
Gruppen
UPN
Avatar
Beispiel:
Unique ID:
<USERNAME_CLAIM>
Email:
<EMAIL_CLAIM>
Display Name:
<NAME_CLAIM>
Groups:
<GROUP_CLAIM>
Welche Claims verwendet werden, hängt vom Identity Provider und Service
Provider ab.
Identity Provider können sowohl einen sichtbaren Benutzernamen als auch eine
interne Benutzer-ID bereitstellen.
Beispiel:
username:
user01
uid:
c038da70-....
Diese Werte erfüllen unterschiedliche Aufgaben.
username kann beispielsweise aus folgendem AD-Attribut stammen:
sAMAccountName
Die interne uid kann dagegen ausschließlich innerhalb des Identity Providers
existieren.
Eine IdP-interne UID sollte daher nicht automatisch als unternehmensweite
Master-ID verwendet werden.
Vor Verwendung muss geklärt werden, ob diese ID:
SAML kann Nachrichten kryptografisch signieren.
Typischer Aufbau:
Identity Provider
Private Key
│
├── signiert Assertion
└── signiert Response
│
▼
Service Provider
Public Certificate
Der Private Key des Identity Providers verbleibt ausschließlich beim
Identity Provider.
Der Service Provider erhält nur das öffentliche Zertifikat.
Empfohlen:
Sign Assertions: Enabled
Damit kann der Service Provider die Integrität der eigentlichen
Authentifizierungsinformationen prüfen.
Abhängig vom Service Provider kann zusätzlich die vollständige SAML Response
signiert werden:
Sign Responses: Enabled
Ob Assertion, Response oder beide signiert werden müssen, hängt vom jeweiligen
Service Provider ab.
Eine Signatur der Assertion sollte mindestens entsprechend den Anforderungen
des Service Providers vorhanden sein.
Optional kann auch der Service Provider seine AuthnRequests signieren.
Dann existiert ein zweites Keypair:
Service Provider
Private Key
│
▼
signierte AuthnRequest
│
▼
Identity Provider
SP Public Certificate
In diesem Fall wird beim Identity Provider ein:
Verification Certificate
hinterlegt.
Wenn beim Identity Provider ein Verification Certificate konfiguriert ist,
kann dieser signierte AuthnRequests erwarten.
Sendet der Service Provider anschließend eine unsignierte Anfrage, kann
beispielsweise folgender Fehler entstehen:
Verification Certificate configured,
but request is not signed.
Wenn der Service Provider keine Requests signiert:
Verification Certificate: leer
Zusätzlich zur Signatur können SAML Assertions verschlüsselt werden.
Dabei besitzt der Service Provider ein eigenes Verschlüsselungs-Keypair:
Identity Provider
│
│ verschlüsselt mit SP Public Key
▼
SAML Assertion
│
▼
Service Provider
entschlüsselt mit Private Key
Der dafür verwendete Private Key verbleibt ausschließlich beim Service Provider.
Transportverschlüsselung über HTTPS bleibt unabhängig davon weiterhin
erforderlich.
SAML-Signing-Zertifikate erfüllen einen anderen Zweck als öffentliche
HTTPS-Zertifikate.
Sie dienen als kryptografischer Vertrauensanker zwischen:
Identity Provider
und
Service Provider
Sie müssen daher nicht denselben Laufzeitregeln wie öffentliche Web-PKI-
Zertifikate folgen.
Für größere Umgebungen kann pro Service Provider ein separates Signing-Keypair
verwendet werden:
Service A → eigenes Signing-Zertifikat
Service B → eigenes Signing-Zertifikat
Service C → eigenes Signing-Zertifikat
Vorteile:
SAML-Zertifikate sollten überwacht und vor Ablauf kontrolliert ersetzt werden.
Beispiel:
Warnung: < 90 Tage
Kritisch: < 30 Tage
Eine typische interne Policy kann beispielsweise eine Laufzeit von:
3–5 Jahren
verwenden.
Die tatsächlich gewählte Laufzeit muss zur eigenen Sicherheits- und
Betriebsrichtlinie passen.
Bei möglicher Schlüsselkompromittierung muss unabhängig vom Ablaufdatum
sofort rotiert werden.
Für neue SAML-Konfigurationen sollte SHA-1 nicht mehr verwendet werden.
Empfohlen:
Signature Algorithm: SHA-256
Digest Algorithm: SHA-256
SHA-512 kann technisch möglich sein, sollte jedoch nur verwendet werden, wenn
beide SAML-Implementierungen dies zuverlässig unterstützen.
SHA-256 bietet üblicherweise die höchste Interoperabilität.
SAML Assertions sollten nur für ein kurzes Zeitfenster akzeptiert werden.
Beispiel:
NotBefore:
-5 Minuten
NotOnOrAfter:
+5 Minuten
Die Zeitreserve berücksichtigt geringe Abweichungen zwischen den Systemuhren.
Alle beteiligten Systeme sollten zuverlässige Zeitquellen verwenden.
Beispiel:
NTP
Chrony
systemd-timesyncd
Große Zeitabweichungen können SAML-Anmeldungen verhindern.
Die Laufzeit der SAML-Session sollte bewusst definiert werden.
Beispiel:
8 Stunden
oder:
12 Stunden
Sehr lange Sessions erhöhen das Risiko bei gestohlenen Sessions.
Die Session-Lifetime des Identity Providers und die lokale Session des
Service Providers sind dabei getrennt zu betrachten.
Einige Service Provider benötigen beim ersten SAML-Login die automatische
Anlage eines lokalen Benutzerobjekts.
Diese Funktion kann beispielsweise heißen:
Self Registration
Automatic User Provisioning
Just-in-Time Provisioning
JIT
Bei zentraler Benutzerfreigabe über den Identity Provider kann dies aktiviert
werden.
Beispiel:
Identity Provider
│
├── Benutzer authentifiziert
├── Benutzer für Anwendung autorisiert
▼
Service Provider
│
└── lokales Benutzerobjekt wird automatisch erzeugt
Die automatisch zugewiesene Standardgruppe sollte keine administrativen
Berechtigungen besitzen.
Wenn möglich sollten Gruppen und Rollen aus einer zentralen Quelle stammen.
Beispiel:
Active Directory
↓
Identity Provider
↓
SAML Groups Claim
↓
Service Provider
Gruppen-Mappings sollten eindeutig dokumentiert werden.
Beispiel:
AD-Gruppe:
Wiki-Users
→
Anwendungsrolle:
User
Administrative Gruppen sollten separat behandelt werden.
Folgende Werte ermitteln bzw. festlegen:
SP Entity ID
ACS URL
gewünschtes Binding
Unique-ID-Attribut
erforderliche Claims
Provider bzw. Enterprise Application anlegen.
Konfigurieren:
ACS URL:
<SP_ACS_URL>
Audience:
<SP_ENTITY_ID>
IdP Entity ID:
<IDP_ENTITY_ID>
Signing Certificate:
<IDP_SIGNING_CERTIFICATE>
Optional:
NameID Mapping
Group Mapping
Session Lifetime
Assertion Lifetime
Metadata aufrufen:
<IDP_METADATA_URL>
Daraus den passenden:
SingleSignOnService
Endpoint übernehmen.
Beispiel:
Entry Point:
<IDP_SSO_ENDPOINT>
Issuer / SP Entity ID:
<SP_ENTITY_ID>
Audience:
<SP_ENTITY_ID>
Certificate:
<IDP_PUBLIC_SIGNING_CERTIFICATE>
Claims entsprechend der Anwendung konfigurieren.
Prüfen:
Browser Developer Tools
→ Network
Insbesondere:
SAMLRequest
Redirect zum IdP
SAMLResponse
POST zur ACS URL
HTTP Status
Zusätzlich Logs von IdP und SP prüfen.
Mögliche Ursachen:
Prüfen:
Host
X-Forwarded-Host
X-Forwarded-Proto
Origin
Prüfen:
Application Slug
Provider-Zuordnung
SSO Endpoint
Binding
Nicht versuchen, SSO-Endpunkte zu erraten.
Stattdessen:
IdP Metadata
→ SingleSignOnService
→ Location
verwenden.
Ursache:
IdP erwartet signierte AuthnRequest
aber:
SP sendet unsignierte AuthnRequest
Lösung:
Entweder Request-Signing am SP konfigurieren oder:
Verification Certificate entfernen
Mögliche Ursachen:
Wenn derselbe Benutzer einmal über LDAP und einmal über SAML erscheint:
User A → LDAP
User A → SAML
muss geprüft werden:
Ein identischer Benutzername oder eine identische E-Mail-Adresse garantiert
nicht automatisch eine Zusammenführung.
Für SAML-Integrationen gelten folgende Grundregeln:
Besonders Änderungen an:
Unique ID
NameID
LDAP Identifier
können dazu führen, dass bestehende Benutzer als neue Identitäten erkannt
werden.
Vor Änderungen müssen daher bestehende Benutzerzuordnungen geprüft werden.
In dieser Dokumentation verwendete Platzhalter:
<IDP-FQDN>
FQDN des Identity Providers
<SP-FQDN>
FQDN des Service Providers
<APPLICATION_SLUG>
Slug / Kennung der Anwendung beim Identity Provider
<IDP_ENTITY_ID>
Entity ID des Identity Providers
<SP_ENTITY_ID>
Entity ID des Service Providers
<IDP_METADATA_URL>
SAML Metadata Endpoint des Identity Providers
<IDP_SSO_ENDPOINT>
SingleSignOnService Endpoint aus den Metadata
<SP_ACS_URL>
Assertion Consumer Service / Callback URL des Service Providers
<IDP_SIGNING_CERTIFICATE>
Signing-Zertifikat des Identity Providers
<USERNAME_CLAIM>
SAML-Attribut für den Benutzer-Identifier
<EMAIL_CLAIM>
SAML-Attribut für die E-Mail-Adresse
<NAME_CLAIM>
SAML-Attribut für den Anzeigenamen
<GROUP_CLAIM>
SAML-Attribut für Gruppen
SP Entity ID
=
Audience im IdP
ACS URL
=
Callback des Service Providers
SSO Entry Point
=
SingleSignOnService Location aus IdP Metadata
IdP Signing Private Key
=
bleibt beim IdP
IdP Signing Certificate
=
wird beim SP hinterlegt
SP Verification Certificate im IdP
=
nur erforderlich, wenn der SP seine Requests signiert
Unique ID
=
muss zum Identitätsmodell der Zielanwendung passen
LDAP + SAML
≠
automatisch dasselbe Benutzerkonto