SnapOtter/apps/docs/de/guide/saml.md

---
description: "Richten Sie SAML-2.0-Single-Sign-On für SnapOtter ein. Schritt-für-Schritt-Anleitungen für Okta, Azure AD / Entra ID, Google Workspace und andere SAML-Identitätsanbieter."
i18n_source_hash: 33dfb8b02a22
i18n_provenance: human
i18n_output_hash: 29cf0d9ed663
---

# SAML SSO {#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.

::: tip 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 {#prerequisites}

- 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 {#quick-start}

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

```yaml
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 {#configuration-reference}

| 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.

::: details 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 {#sp-metadata-and-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 {#provider-setup}

### Okta {#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 {#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 {#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 {#generic-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 {#user-provisioning}

### Automatisches Erstellen {#auto-create}

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 {#auto-link}

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 {#attribute-mapping}

| 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 {#sso-enforcement}

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 {#using-saml-alongside-oidc}

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 {#troubleshooting}

### Assertion-Validierung fehlgeschlagen {#assertion-validation-failed}

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 {#missing-attributes}

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 {#clock-skew}

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" {#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 {#login-redirects-back-with-error}

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)