SAML SSO

SnapOtter ondersteunt SAML 2.0 voor single sign-on. Gebruikers kunnen inloggen via een externe identiteitsprovider (Okta, Azure AD / Entra ID, Google Workspace of een standaard SAML 2.0-IdP) in plaats van lokale authenticatie met gebruikersnaam/wachtwoord.

Enterprise-functie

SAML SSO vereist een team- of enterprise-licentie met de saml_sso-functie. Als SAML_ENABLED=true is ingesteld zonder een geldige licentie, worden de SAML-routes stilzwijgend overgeslagen en wordt er een waarschuwing gelogd.

Vereisten

• Een draaiende SnapOtter-instantie bereikbaar op een publieke URL
• EXTERNAL_URL ingesteld op die publieke URL (bijv. https://photos.example.com)
• Een team- of enterprise-licentiesleutel met de saml_sso-functie
• Adminrechten voor je SAML-identiteitsprovider

Snelstart

Voeg deze omgevingsvariabelen toe aan je docker-compose.yml:

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

Herstart de container. Een knop "Aanmelden met SAML" (of het label ingesteld door SAML_PROVIDER_NAME) verschijnt op de aanmeldpagina.

Configuratiereferentie

Variabele	Standaard	Beschrijving
SAML_ENABLED	false	SAML-login inschakelen.
SAML_IDP_SSO_URL		SSO-eindpunt-URL van de IdP. Vereist wanneer SAML is ingeschakeld.
SAML_IDP_CERTIFICATE		X.509-ondertekeningscertificaat van de IdP in PEM-formaat (de certificaattekst zelf, niet een bestandspad). Vereist wanneer SAML is ingeschakeld.
EXTERNAL_URL		De publieke URL waarop SnapOtter bereikbaar is. Vereist wanneer SAML is ingeschakeld.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	SP Entity ID / Audience URI verzonden naar de IdP.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	Assertion Consumer Service (ACS)-URL.
SAML_AUTO_CREATE_USERS	true	Maak automatisch een lokaal gebruikersaccount aan bij de eerste SAML-login.
SAML_AUTO_LINK_USERS	false	Koppel een SAML-identiteit aan een bestaande lokale gebruiker als het e-mailadres overeenkomt.
SAML_DEFAULT_ROLE	user	Rol toegewezen aan automatisch aangemaakte SAML-gebruikers. Een van admin, editor of user.
SAML_PROVIDER_NAME		Weergavelabel voor de SAML-aanmeldknop in de frontend (bijv. "Okta", "Azure AD"). Indien leeg, staat er "SAML" op de knop.
SAML_USERNAME_ATTRIBUTE		SAML-assertie-attribuut dat als gebruikersnaam wordt gebruikt. Indien leeg, wordt teruggevallen op het lokale deel van de e-mail, daarna NameID.
SAML_EMAIL_ATTRIBUTE	email	SAML-assertie-attribuut dat als e-mailadres van de gebruiker wordt gebruikt.

De server weigert te starten als SAML_ENABLED=true en een van de drie vereiste variabelen (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL) ontbreekt.

Beveiligingsnotities

Zowel wantAuthnResponseSigned als wantAssertionsSigned zijn hardgecodeerd op true. SnapOtter wijst niet-ondertekende of onjuist ondertekende SAML-responses af. Asserties van een vertrouwde IdP worden behandeld als e-mailgeverifieerd.

Alleen SP-geïnitieerde login wordt ondersteund. SnapOtter ondersteunt geen IdP-geïnitieerde (ongevraagde) login of Single Logout (SLO). Uitloggen bij SnapOtter logt de gebruiker niet uit bij de IdP.

SP-metadata en URL's

Je IdP heeft drie waarden van SnapOtter nodig:

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

Als EXTERNAL_URL bijvoorbeeld https://photos.example.com is:

• ACS-URL: https://photos.example.com/api/auth/saml/callback
• Entity ID: https://photos.example.com/api/auth/saml/metadata
• Metadata-eindpunt: https://photos.example.com/api/auth/saml/metadata (retourneert XML)

Sommige IdP's kunnen de SP-metadata-URL rechtstreeks importeren, waardoor de ACS-URL en Entity ID automatisch worden ingevuld.

Providerinstellingen

Okta

1. Ga in de Okta-adminconsole naar Applications > Create App Integration.
2. Selecteer SAML 2.0 en klik op Next.
3. Stel een naam in (bijv. "SnapOtter") en klik op Next.
4. Configureer de SAML-instellingen:
   • Single sign-on URL: Je ACS-URL (bijv. https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): Je Entity ID (bijv. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. Voeg onder Attribute Statements email toe, toegewezen aan user.email.
6. Klik op Next, daarna op Finish.
7. Ga naar het tabblad Sign On, klik op View SAML setup instructions en kopieer:
   • Identity Provider Single Sign-On URL naar SAML_IDP_SSO_URL
   • X.509 Certificate naar SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. Ga in de Azure-portal naar Microsoft Entra ID > Enterprise applications > New application.
2. Klik op Create your own application, noem het "SnapOtter" en selecteer Integrate any other application you don't find in the gallery.
3. Ga naar Single sign-on > SAML en klik op Edit in de sectie Basic SAML Configuration:
   • Identifier (Entity ID): Je Entity ID (bijv. https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): Je ACS-URL (bijv. https://photos.example.com/api/auth/saml/callback)
4. Download onder SAML Certificates het Certificate (Base64).
5. Kopieer onder Set up SnapOtter de Login URL.
6. Stel SAML_IDP_SSO_URL in op de Login URL en SAML_IDP_CERTIFICATE op de inhoud van het gedownloade certificaat.
7. Wijs gebruikers of groepen toe aan de applicatie onder Users and groups.

Google Workspace

1. Ga in de Google-adminconsole naar Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Noem de app "SnapOtter" en klik op Continue.
3. Kopieer op de pagina Google Identity Provider details de SSO URL en download het Certificate. Klik op Continue.
4. Configureer de Service Provider-details:
   • ACS URL: Je ACS-URL (bijv. https://photos.example.com/api/auth/saml/callback)
   • Entity ID: Je Entity ID (bijv. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Klik op Continue, daarna op Finish.
6. Zet de app ON voor je organisatie-eenheden.
7. Stel SAML_IDP_SSO_URL in op de SSO URL uit stap 3 en SAML_IDP_CERTIFICATE op de inhoud van het gedownloade certificaat.

Generieke SAML 2.0-IdP

Voor elke SAML 2.0-compatibele identiteitsprovider:

1. Maak een nieuwe SAML-applicatie/serviceprovider aan in je IdP.
2. Stel de ACS-URL in op ${EXTERNAL_URL}/api/auth/saml/callback.
3. Stel de Entity ID / Audience in op ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Configureer de IdP om het e-mailadres van de gebruiker te verzenden in een attribuut genaamd email (of stel SAML_EMAIL_ATTRIBUTE in om overeen te komen met de attribuutnaam van je IdP).
5. Kopieer de IdP SSO URL en het ondertekeningscertificaat naar SAML_IDP_SSO_URL en SAML_IDP_CERTIFICATE.

Gebruikersprovisioning

Automatisch aanmaken

Wanneer SAML_AUTO_CREATE_USERS op true staat (de standaard), wordt er een lokaal gebruikersaccount aangemaakt wanneer iemand voor het eerst via SAML inlogt. De rol wordt ingesteld op SAML_DEFAULT_ROLE.

De gebruikersnaam wordt afgeleid in deze volgorde:

1. De waarde van het assertie-attribuut opgegeven door SAML_USERNAME_ATTRIBUTE (indien ingesteld en aanwezig)
2. Het lokale deel van het e-mailadres (alles vóór @)
3. De SAML NameID

Als er een botsing van gebruikersnamen optreedt, wordt er een numeriek achtervoegsel toegevoegd (bijv. jane wordt jane_2).

Automatisch koppelen

Wanneer SAML_AUTO_LINK_USERS op true staat, koppelt SnapOtter een SAML-identiteit aan een bestaand lokaal account als de e-mailadressen overeenkomen. Dit is handig wanneer je vooraf aangemaakte gebruikersaccounts hebt en wilt dat ze SSO gaan gebruiken zonder hun gegevens te verliezen.

WARNING

Schakel automatisch koppelen alleen in als je je SAML-IdP vertrouwt om e-mailadressen te verifiëren. Een niet-geverifieerd e-mailadres van een verkeerd geconfigureerde IdP zou iemand in staat kunnen stellen het account van een andere gebruiker over te nemen.

Attribuuttoewijzing

SnapOtter-veld	Bron	Configuratie
E-mail	Assertie-attribuut	SAML_EMAIL_ATTRIBUTE (standaard: email)
Gebruikersnaam	Assertie-attribuut, e-mail of NameID	SAML_USERNAME_ATTRIBUTE (zie afleidingsvolgorde hierboven)
Externe ID	NameID	Altijd de SAML NameID, niet configureerbaar

SSO-afdwinging

Als je wilt vereisen dat alle gebruikers via SAML (of OIDC) inloggen en lokale wachtwoordlogin wilt blokkeren, schakel dan SSO-afdwinging in:

1. Zorg dat de sso_enforcement-enterprisefunctie gelicentieerd is (beschikbaar op team- en enterprise-plannen).
2. Zet in Admin Settings > Security de schakelaar SSO Enforcement aan.
3. Stel een break-glass-gebruikersnaam in: dit is het ene lokale account dat nog steeds met een wachtwoord kan inloggen, voor noodtoegang als de IdP onbereikbaar is.

Wanneer SSO-afdwinging actief is, retourneert elke lokale inlogpoging (behalve voor de break-glass-gebruiker) een 403-fout met de melding "Local password login is disabled. Please use SSO."

TIP

Configureer altijd een break-glass-gebruikersnaam voordat je SSO-afdwinging inschakelt. Zonder deze kun je buitengesloten raken van SnapOtter als je IdP uitvalt.

SAML naast OIDC gebruiken

SAML en OIDC kunnen tegelijkertijd worden ingeschakeld. Wanneer beide actief zijn, toont de aanmeldpagina aparte knoppen voor elke provider (gelabeld door SAML_PROVIDER_NAME en OIDC_PROVIDER_NAME). Gebruikers kunnen met beide methoden inloggen.

Beide providers delen dezelfde instellingen voor automatisch aanmaken, automatisch koppelen en SSO-afdwinging onafhankelijk van elkaar: elk heeft zijn eigen *_AUTO_CREATE_USERS-, *_AUTO_LINK_USERS- en *_DEFAULT_ROLE-variabelen.

Problemen oplossen

Assertievalidatie mislukt

De handtekening van de SAML-response of de assertiehandtekening kon niet worden geverifieerd. Controleer:

• Het certificaat in SAML_IDP_CERTIFICATE komt overeen met het huidige ondertekeningscertificaat in je IdP (certificaten roteren, dus controleer op vervaldatum)
• Het certificaat is in PEM-formaat (begint met -----BEGIN CERTIFICATE-----)
• Het certificaat is de volledige tekst, niet een bestandspad
• De ACS-URL en Entity ID geconfigureerd in je IdP komen exact overeen met de waarden van SnapOtter (schema, host, poort, pad)

Ontbrekende attributen

Als gebruikersnamen of e-mailadressen leeg zijn na het inloggen, verzendt je IdP mogelijk niet de verwachte attributen. Controleer:

• Je IdP is geconfigureerd om een email-attribuut vrij te geven (of waar SAML_EMAIL_ATTRIBUTE ook op is ingesteld)
• Verifieer bij gebruik van SAML_USERNAME_ATTRIBUTE dat dat attribuut in de assertie is opgenomen
• Sommige IdP's vereisen expliciete configuratie van attribuuttoewijzing voordat ze claims vrijgeven

Klokverschil

SAML-asserties bevatten tijdstempelvoorwaarden (NotBefore, NotOnOrAfter). Als je serverklok en de klok van de IdP niet gelijklopen, mislukt de assertievalidatie. Draai NTP op beide machines om de klokken uitgelijnd te houden.

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

Deze waarschuwing verschijnt in de serverlogs wanneer SAML_ENABLED=true maar de licentie de saml_sso-functie niet bevat. Verifieer je licentiesleutel en plan. De saml_sso-functie is beschikbaar op team- en enterprise-plannen.

Login stuurt terug met fout

Als het klikken op de SAML-aanmeldknop je terugstuurt naar de aanmeldpagina met een fout, controleer dan de serverlogs voor details. Veelvoorkomende oorzaken:

• De IdP SSO URL is onbereikbaar vanaf de server
• De IdP heeft het authenticatieverzoek geweigerd (controleer de auditlogs van de IdP)
• De IdP retourneerde een niet-ondertekende response (SnapOtter vereist dat zowel de response als de assertie ondertekend zijn)