SAML SSO

SnapOtter unterstützt SAML 2.0 für Single Sign-On. Benutzer können sich über einen externen Identitätsanbieter (Okta, Azure AD / Entra ID, Google Workspace oder einen beliebigen standardkonformen SAML-2.0-IdP) anmelden, anstatt sich lokal mit Benutzername/Passwort zu authentifizieren.

Enterprise-Funktion

SAML SSO erfordert eine team- oder enterprise-Lizenz mit der Funktion saml_sso. Wenn SAML_ENABLED=true ohne gültige Lizenz gesetzt ist, werden die SAML-Routen stillschweigend übersprungen und eine Warnung protokolliert.

Voraussetzungen

• Eine laufende SnapOtter-Instanz, die unter einer öffentlichen URL erreichbar ist
• EXTERNAL_URL auf diese öffentliche URL gesetzt (z. B. https://photos.example.com)
• Ein team- oder enterprise-Lizenzschlüssel mit der Funktion saml_sso
• Admin-Zugriff auf Ihren SAML-Identitätsanbieter

Schnellstart

Fügen Sie diese Umgebungsvariablen zu Ihrer docker-compose.yml hinzu:

services:
  snapotter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      SNAPOTTER_LICENSE_KEY: "your-license-key"
      SAML_ENABLED: "true"
      SAML_IDP_SSO_URL: "https://idp.example.com/sso/saml"
      SAML_IDP_CERTIFICATE: |
        MIICpDCCAYwCCQDU+pQ4pHgSpDANBgkqhkiG9w0BAQsFADAUMRIw
        ...your IdP's signing certificate in PEM format...
        EAYHKoZIzj0CAQYFK4EEACIDYgAE

Starten Sie den Container neu. Eine Schaltfläche "Mit SAML anmelden" (oder die durch SAML_PROVIDER_NAME gesetzte Bezeichnung) erscheint auf der Anmeldeseite.

Konfigurationsreferenz

Variable	Standard	Beschreibung
SAML_ENABLED	false	SAML-Anmeldung aktivieren.
SAML_IDP_SSO_URL		SSO-Endpunkt-URL des IdP. Erforderlich, wenn SAML aktiviert ist.
SAML_IDP_CERTIFICATE		X.509-Signaturzertifikat des IdP im PEM-Format (der Zertifikatstext selbst, nicht ein Dateipfad). Erforderlich, wenn SAML aktiviert ist.
EXTERNAL_URL		Die öffentliche URL, unter der SnapOtter erreichbar ist. Erforderlich, wenn SAML aktiviert ist.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	An den IdP gesendete SP-Entity-ID / Audience-URI.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	Assertion-Consumer-Service-URL (ACS).
SAML_AUTO_CREATE_USERS	true	Bei der ersten SAML-Anmeldung automatisch ein lokales Benutzerkonto erstellen.
SAML_AUTO_LINK_USERS	false	Eine SAML-Identität mit einem bestehenden lokalen Benutzer verknüpfen, wenn die E-Mail-Adresse übereinstimmt.
SAML_DEFAULT_ROLE	user	Rolle, die automatisch erstellten SAML-Benutzern zugewiesen wird. Eine von admin, editor oder user.
SAML_PROVIDER_NAME		Anzeigebezeichnung für die SAML-Anmeldeschaltfläche im Frontend (z. B. "Okta", "Azure AD"). Wenn leer, zeigt die Schaltfläche "SAML" an.
SAML_USERNAME_ATTRIBUTE		SAML-Assertion-Attribut, das als Benutzername verwendet wird. Wenn leer, wird auf den lokalen Teil der E-Mail und dann auf die NameID zurückgegriffen.
SAML_EMAIL_ATTRIBUTE	email	SAML-Assertion-Attribut, das als E-Mail-Adresse des Benutzers verwendet wird.

Der Server startet nicht, wenn SAML_ENABLED=true und eine der drei erforderlichen Variablen (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL) fehlt.

Sicherheitshinweise

Sowohl wantAuthnResponseSigned als auch wantAssertionsSigned sind fest auf true codiert. SnapOtter lehnt unsignierte oder unsachgemäß signierte SAML-Antworten ab. Assertions von einem vertrauenswürdigen IdP werden als E-Mail-verifiziert behandelt.

Es wird nur SP-initiierte Anmeldung unterstützt. SnapOtter unterstützt keine IdP-initiierte (unaufgeforderte) Anmeldung und kein Single Logout (SLO). Das Abmelden von SnapOtter meldet den Benutzer nicht vom IdP ab.

SP-Metadaten und URLs

Ihr IdP benötigt drei Werte von SnapOtter:

Feld	Wert
ACS-URL (Assertion Consumer Service)	${EXTERNAL_URL}/api/auth/saml/callback
Entity-ID / Audience-URI	${EXTERNAL_URL}/api/auth/saml/metadata
SP-Metadaten (XML)	GET ${EXTERNAL_URL}/api/auth/saml/metadata

Wenn EXTERNAL_URL beispielsweise https://photos.example.com ist:

• ACS-URL: https://photos.example.com/api/auth/saml/callback
• Entity-ID: https://photos.example.com/api/auth/saml/metadata
• Metadaten-Endpunkt: https://photos.example.com/api/auth/saml/metadata (gibt XML zurück)

Manche IdPs können die SP-Metadaten-URL direkt importieren, wodurch die ACS-URL und die Entity-ID automatisch ausgefüllt werden.

Anbietereinrichtung

Okta

1. Gehen Sie in der Okta-Admin-Konsole zu Applications > Create App Integration.
2. Wählen Sie SAML 2.0 und klicken Sie auf Next.
3. Legen Sie einen Namen fest (z. B. "SnapOtter") und klicken Sie auf Next.
4. Konfigurieren Sie die SAML-Einstellungen:
   • Single sign-on URL: Ihre ACS-URL (z. B. https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): Ihre Entity-ID (z. B. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. Fügen Sie unter Attribute Statements email hinzu, zugeordnet zu user.email.
6. Klicken Sie auf Next, dann auf Finish.
7. Gehen Sie zur Registerkarte Sign On, klicken Sie auf View SAML setup instructions und kopieren Sie:
   • Identity Provider Single Sign-On URL in SAML_IDP_SSO_URL
   • X.509 Certificate in SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. Gehen Sie im Azure-Portal zu Microsoft Entra ID > Enterprise applications > New application.
2. Klicken Sie auf Create your own application, benennen Sie sie "SnapOtter" und wählen Sie Integrate any other application you don't find in the gallery.
3. Gehen Sie zu Single sign-on > SAML und klicken Sie im Abschnitt Basic SAML Configuration auf Edit:
   • Identifier (Entity ID): Ihre Entity-ID (z. B. https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): Ihre ACS-URL (z. B. https://photos.example.com/api/auth/saml/callback)
4. Laden Sie unter SAML Certificates das Certificate (Base64) herunter.
5. Kopieren Sie unter Set up SnapOtter die Login URL.
6. Setzen Sie SAML_IDP_SSO_URL auf die Login-URL und SAML_IDP_CERTIFICATE auf den Inhalt des heruntergeladenen Zertifikats.
7. Weisen Sie der Anwendung unter Users and groups Benutzer oder Gruppen zu.

Google Workspace

1. Gehen Sie in der Google-Admin-Konsole zu Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Benennen Sie die App "SnapOtter" und klicken Sie auf Continue.
3. Kopieren Sie auf der Seite Google Identity Provider details die SSO URL und laden Sie das Certificate herunter. Klicken Sie auf Continue.
4. Konfigurieren Sie die Service-Provider-Details:
   • ACS URL: Ihre ACS-URL (z. B. https://photos.example.com/api/auth/saml/callback)
   • Entity ID: Ihre Entity-ID (z. B. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Klicken Sie auf Continue, dann auf Finish.
6. Schalten Sie die App für Ihre Organisationseinheiten ON.
7. Setzen Sie SAML_IDP_SSO_URL auf die SSO-URL aus Schritt 3 und SAML_IDP_CERTIFICATE auf den Inhalt des heruntergeladenen Zertifikats.

Generischer SAML-2.0-IdP

Für jeden SAML-2.0-konformen Identitätsanbieter:

1. Erstellen Sie eine neue SAML-Anwendung/einen neuen Service Provider in Ihrem IdP.
2. Setzen Sie die ACS-URL auf ${EXTERNAL_URL}/api/auth/saml/callback.
3. Setzen Sie die Entity-ID / Audience auf ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Konfigurieren Sie den IdP so, dass er die E-Mail des Benutzers in einem Attribut namens email sendet (oder setzen Sie SAML_EMAIL_ATTRIBUTE, damit es dem Attributnamen Ihres IdP entspricht).
5. Kopieren Sie die IdP-SSO-URL und das Signaturzertifikat in SAML_IDP_SSO_URL und SAML_IDP_CERTIFICATE.

Benutzerbereitstellung

Automatisches Erstellen

Wenn SAML_AUTO_CREATE_USERS auf true (die Voreinstellung) steht, wird beim ersten Anmelden per SAML ein lokales Benutzerkonto erstellt. Die Rolle wird auf SAML_DEFAULT_ROLE gesetzt.

Der Benutzername wird in dieser Reihenfolge abgeleitet:

1. Der Wert des durch SAML_USERNAME_ATTRIBUTE angegebenen Assertion-Attributs (falls gesetzt und vorhanden)
2. Der lokale Teil der E-Mail-Adresse (alles vor @)
3. Die SAML-NameID

Bei einer Kollision des Benutzernamens wird ein numerisches Suffix angehängt (z. B. jane wird zu jane_2).

Automatisches Verknüpfen

Wenn SAML_AUTO_LINK_USERS auf true steht, verknüpft SnapOtter eine SAML-Identität mit einem bestehenden lokalen Konto, wenn die E-Mail-Adressen übereinstimmen. Das ist nützlich, wenn Sie Benutzerkonten vorab erstellt haben und möchten, dass diese SSO nutzen, ohne ihre Daten zu verlieren.

WARNING

Aktivieren Sie das automatische Verknüpfen nur, wenn Sie Ihrem SAML-IdP zutrauen, E-Mail-Adressen zu verifizieren. Eine nicht verifizierte E-Mail von einem fehlkonfigurierten IdP könnte es jemandem ermöglichen, das Konto eines anderen Benutzers zu übernehmen.

Attributzuordnung

SnapOtter-Feld	Quelle	Konfiguration
E-Mail	Assertion-Attribut	SAML_EMAIL_ATTRIBUTE (Standard: email)
Benutzername	Assertion-Attribut, E-Mail oder NameID	SAML_USERNAME_ATTRIBUTE (siehe Ableitungsreihenfolge oben)
Externe ID	NameID	Immer die SAML-NameID, nicht konfigurierbar

SSO-Erzwingung

Wenn Sie verlangen möchten, dass sich alle Benutzer per SAML (oder OIDC) anmelden, und die lokale Passwortanmeldung blockieren möchten, aktivieren Sie die SSO-Erzwingung:

1. Stellen Sie sicher, dass die Enterprise-Funktion sso_enforcement lizenziert ist (verfügbar in den team- und enterprise-Plänen).
2. Schalten Sie unter Admin-Einstellungen > Sicherheit die SSO-Erzwingung ein.
3. Legen Sie einen Break-Glass-Benutzernamen fest: Dies ist das eine lokale Konto, das sich bei Notfallzugriff weiterhin mit einem Passwort anmelden kann, falls der IdP nicht erreichbar ist.

Wenn die SSO-Erzwingung aktiv ist, gibt jeder lokale Anmeldeversuch (außer für den Break-Glass-Benutzer) einen 403-Fehler mit der Meldung "Local password login is disabled. Please use SSO." zurück.

TIP

Konfigurieren Sie immer einen Break-Glass-Benutzernamen, bevor Sie die SSO-Erzwingung aktivieren. Andernfalls könnten Sie aus SnapOtter ausgesperrt werden, falls Ihr IdP ausfällt.

SAML zusammen mit OIDC verwenden

SAML und OIDC können gleichzeitig aktiviert werden. Wenn beide aktiv sind, zeigt die Anmeldeseite separate Schaltflächen für jeden Anbieter an (beschriftet durch SAML_PROVIDER_NAME und OIDC_PROVIDER_NAME). Benutzer können sich mit beiden Methoden anmelden.

Beide Anbieter teilen sich die Einstellungen für automatisches Erstellen, automatisches Verknüpfen und SSO-Erzwingung unabhängig voneinander: Jeder hat seine eigenen Variablen *_AUTO_CREATE_USERS, *_AUTO_LINK_USERS und *_DEFAULT_ROLE.

Fehlerbehebung

Assertion-Validierung fehlgeschlagen

Die Signatur der SAML-Antwort oder der Assertion konnte nicht verifiziert werden. Prüfen Sie:

• Das Zertifikat in SAML_IDP_CERTIFICATE stimmt mit dem aktuellen Signaturzertifikat in Ihrem IdP überein (Zertifikate rotieren, prüfen Sie also auf Ablauf)
• Das Zertifikat ist im PEM-Format (beginnt mit -----BEGIN CERTIFICATE-----)
• Das Zertifikat ist der vollständige Text, kein Dateipfad
• Die in Ihrem IdP konfigurierte ACS-URL und Entity-ID stimmen exakt mit den Werten von SnapOtter überein (Schema, Host, Port, Pfad)

Fehlende Attribute

Wenn Benutzernamen oder E-Mails nach der Anmeldung leer sind, sendet Ihr IdP möglicherweise nicht die erwarteten Attribute. Prüfen Sie:

• Ihr IdP ist so konfiguriert, dass er ein Attribut email freigibt (oder das, worauf SAML_EMAIL_ATTRIBUTE gesetzt ist)
• Wenn Sie SAML_USERNAME_ATTRIBUTE verwenden, prüfen Sie, ob dieses Attribut in der Assertion enthalten ist
• Manche IdPs erfordern eine explizite Attributzuordnungskonfiguration, bevor sie Claims freigeben

Uhrenabweichung

SAML-Assertions enthalten Zeitstempelbedingungen (NotBefore, NotOnOrAfter). Wenn die Uhr Ihres Servers und die Uhr des IdP nicht synchron sind, schlägt die Assertion-Validierung fehl. Führen Sie NTP auf beiden Maschinen aus, um die Uhren aufeinander abzustimmen.

"SAML is enabled via env but saml_sso enterprise feature is not licensed"

Diese Warnung erscheint in den Serverprotokollen, wenn SAML_ENABLED=true, die Lizenz aber die Funktion saml_sso nicht enthält. Überprüfen Sie Ihren Lizenzschlüssel und Plan. Die Funktion saml_sso ist in den team- und enterprise-Plänen verfügbar.

Anmeldung leitet mit Fehler zurück

Wenn das Klicken auf die SAML-Anmeldeschaltfläche mit einem Fehler zurück auf die Anmeldeseite leitet, prüfen Sie die Serverprotokolle auf Details. Häufige Ursachen:

• Die IdP-SSO-URL ist vom Server aus nicht erreichbar
• Der IdP hat die Authentifizierungsanfrage abgelehnt (prüfen Sie die Audit-Protokolle des IdP)
• Der IdP hat eine unsignierte Antwort zurückgegeben (SnapOtter verlangt, dass sowohl die Antwort als auch die Assertion signiert sind)