SAML SSO

SnapOtter stöder SAML 2.0 för single sign-on. Användare kan logga in via en extern identitetsleverantör (Okta, Azure AD / Entra ID, Google Workspace eller vilken standard-SAML 2.0-IdP som helst) i stället för lokal autentisering med användarnamn/lösenord.

Enterprise-funktion

SAML SSO kräver en team- eller enterprise-licens med funktionen saml_sso. Om SAML_ENABLED=true är satt utan en giltig licens hoppas SAML-rutterna tyst över och en varning loggas.

Förutsättningar

• En körande SnapOtter-instans nåbar på en publik URL
• EXTERNAL_URL satt till den publika URL:n (t.ex. https://photos.example.com)
• En team- eller enterprise-licensnyckel med funktionen saml_sso
• Administratörsåtkomst till din SAML-identitetsleverantör

Snabbstart

Lägg till dessa miljövariabler i din 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

Starta om containern. En "Logga in med SAML"-knapp (eller etiketten satt av SAML_PROVIDER_NAME) visas på inloggningssidan.

Konfigurationsreferens

Variabel	Standard	Beskrivning
SAML_ENABLED	false	Aktivera SAML-inloggning.
SAML_IDP_SSO_URL		IdP:ns SSO-slutpunkts-URL. Krävs när SAML är aktiverat.
SAML_IDP_CERTIFICATE		IdP:ns X.509-signeringscertifikat i PEM-format (själva certifikattexten, inte en filsökväg). Krävs när SAML är aktiverat.
EXTERNAL_URL		Den publika URL där SnapOtter är nåbar. Krävs när SAML är aktiverat.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	SP Entity ID / Audience URI som skickas till IdP:n.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	Assertion Consumer Service (ACS)-URL.
SAML_AUTO_CREATE_USERS	true	Skapa automatiskt ett lokalt användarkonto vid första SAML-inloggningen.
SAML_AUTO_LINK_USERS	false	Länka en SAML-identitet till en befintlig lokal användare om e-postadressen matchar.
SAML_DEFAULT_ROLE	user	Roll som tilldelas automatiskt skapade SAML-användare. En av admin, editor eller user.
SAML_PROVIDER_NAME		Visningsetikett för SAML-inloggningsknappen i frontend (t.ex. "Okta", "Azure AD"). Om tomt står det "SAML" på knappen.
SAML_USERNAME_ATTRIBUTE		SAML-assertion-attribut som används som användarnamn. Om tomt faller det tillbaka till e-postadressens lokala del, sedan NameID.
SAML_EMAIL_ATTRIBUTE	email	SAML-assertion-attribut som används som användarens e-postadress.

Servern vägrar att starta om SAML_ENABLED=true och någon av de tre obligatoriska variablerna (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL) saknas.

Säkerhetsanteckningar

Både wantAuthnResponseSigned och wantAssertionsSigned är hårdkodade till true. SnapOtter avvisar osignerade eller felaktigt signerade SAML-svar. Assertions från en betrodd IdP behandlas som e-postverifierade.

Endast SP-initierad inloggning stöds. SnapOtter stöder inte IdP-initierad (oombedd) inloggning eller Single Logout (SLO). Att logga ut från SnapOtter loggar inte ut användaren från IdP:n.

SP-metadata och URL:er

Din IdP behöver tre värden från SnapOtter:

Fält	Värde
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

Om till exempel EXTERNAL_URL är https://photos.example.com:

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

Vissa IdP:er kan importera SP-metadata-URL:n direkt, vilket automatiskt fyller i ACS-URL:n och Entity ID.

Leverantörskonfiguration

Okta

1. I Okta-administratörskonsolen, gå till Applications > Create App Integration.
2. Välj SAML 2.0 och klicka på Next.
3. Ange ett namn (t.ex. "SnapOtter") och klicka på Next.
4. Konfigurera SAML-inställningarna:
   • Single sign-on URL: Din ACS-URL (t.ex. https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): Ditt Entity ID (t.ex. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. Under Attribute Statements, lägg till email mappat till user.email.
6. Klicka på Next, sedan Finish.
7. Gå till fliken Sign On, klicka på View SAML setup instructions och kopiera:
   • Identity Provider Single Sign-On URL till SAML_IDP_SSO_URL
   • X.509 Certificate till SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. I Azure-portalen, gå till Microsoft Entra ID > Enterprise applications > New application.
2. Klicka på Create your own application, döp den till "SnapOtter" och välj Integrate any other application you don't find in the gallery.
3. Gå till Single sign-on > SAML och klicka på Edit i avsnittet Basic SAML Configuration:
   • Identifier (Entity ID): Ditt Entity ID (t.ex. https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): Din ACS-URL (t.ex. https://photos.example.com/api/auth/saml/callback)
4. Under SAML Certificates, ladda ner Certificate (Base64).
5. Under Set up SnapOtter, kopiera Login URL.
6. Sätt SAML_IDP_SSO_URL till Login-URL:n och SAML_IDP_CERTIFICATE till innehållet i det nedladdade certifikatet.
7. Tilldela användare eller grupper till applikationen under Users and groups.

Google Workspace

1. I Google Admin-konsolen, gå till Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Döp appen till "SnapOtter" och klicka på Continue.
3. På sidan Google Identity Provider details, kopiera SSO URL och ladda ner Certificate. Klicka på Continue.
4. Konfigurera Service Provider-detaljerna:
   • ACS URL: Din ACS-URL (t.ex. https://photos.example.com/api/auth/saml/callback)
   • Entity ID: Ditt Entity ID (t.ex. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Klicka på Continue, sedan Finish.
6. Slå PÅ appen för dina organisationsenheter.
7. Sätt SAML_IDP_SSO_URL till SSO-URL:n från steg 3 och SAML_IDP_CERTIFICATE till innehållet i det nedladdade certifikatet.

Generisk SAML 2.0-IdP

För vilken SAML 2.0-kompatibel identitetsleverantör som helst:

1. Skapa en ny SAML-applikation/tjänsteleverantör i din IdP.
2. Sätt ACS-URL till ${EXTERNAL_URL}/api/auth/saml/callback.
3. Sätt Entity ID / Audience till ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Konfigurera IdP:n att skicka användarens e-post i ett attribut med namnet email (eller sätt SAML_EMAIL_ATTRIBUTE för att matcha din IdP:s attributnamn).
5. Kopiera IdP SSO URL och signeringscertifikat till SAML_IDP_SSO_URL och SAML_IDP_CERTIFICATE.

Användarprovisionering

Skapa automatiskt

När SAML_AUTO_CREATE_USERS är true (standard) skapas ett lokalt användarkonto första gången någon loggar in via SAML. Rollen sätts till SAML_DEFAULT_ROLE.

Användarnamnet härleds i denna ordning:

1. Värdet av assertion-attributet som anges av SAML_USERNAME_ATTRIBUTE (om det är satt och finns)
2. Den lokala delen av e-postadressen (allt före @)
3. SAML NameID

Om en användarnamnskollision uppstår läggs ett numeriskt suffix till (t.ex. jane blir jane_2).

Länka automatiskt

När SAML_AUTO_LINK_USERS är true länkar SnapOtter en SAML-identitet till ett befintligt lokalt konto om e-postadresserna matchar. Detta är användbart när du har förskapade användarkonton och vill att de ska börja använda SSO utan att förlora sina data.

WARNING

Aktivera endast automatisk länkning om du litar på att din SAML-IdP verifierar e-postadresser. En overifierad e-postadress från en felkonfigurerad IdP kan tillåta någon att ta över en annan användares konto.

Attributmappning

SnapOtter-fält	Källa	Konfiguration
E-post	Assertion-attribut	SAML_EMAIL_ATTRIBUTE (standard: email)
Användarnamn	Assertion-attribut, e-post eller NameID	SAML_USERNAME_ATTRIBUTE (se härledningsordning ovan)
Externt ID	NameID	Alltid SAML NameID, inte konfigurerbart

Framtvingande av SSO

Om du vill kräva att alla användare loggar in via SAML (eller OIDC) och blockera lokal lösenordsinloggning, aktiverar du framtvingande av SSO:

1. Säkerställ att enterprise-funktionen sso_enforcement är licensierad (tillgänglig på team- och enterprise-planer).
2. I Admin Settings > Security, slå på SSO Enforcement.
3. Sätt ett break-glass-användarnamn: detta är det enda lokala konto som fortfarande kan logga in med ett lösenord, för nödåtkomst om IdP:n är onåbar.

När framtvingande av SSO är aktivt returnerar varje lokalt inloggningsförsök (utom för break-glass-användaren) ett 403-fel med meddelandet "Local password login is disabled. Please use SSO."

TIP

Konfigurera alltid ett break-glass-användarnamn innan du aktiverar framtvingande av SSO. Utan det kan du bli utelåst från SnapOtter om din IdP går ner.

Använda SAML tillsammans med OIDC

SAML och OIDC kan aktiveras samtidigt. När båda är aktiva visar inloggningssidan separata knappar för varje leverantör (märkta med SAML_PROVIDER_NAME och OIDC_PROVIDER_NAME). Användare kan logga in med endera metoden.

Båda leverantörerna delar samma inställningar för automatiskt skapande, automatisk länkning och framtvingande av SSO oberoende av varandra: var och en har sina egna *_AUTO_CREATE_USERS-, *_AUTO_LINK_USERS- och *_DEFAULT_ROLE-variabler.

Felsökning

Assertion-validering misslyckades

Signaturen på SAML-svaret eller assertion-signaturen kunde inte verifieras. Kontrollera:

• Certifikatet i SAML_IDP_CERTIFICATE matchar det aktuella signeringscertifikatet i din IdP (certifikat roteras, så kontrollera utgångsdatum)
• Certifikatet är i PEM-format (börjar med -----BEGIN CERTIFICATE-----)
• Certifikatet är den fullständiga texten, inte en filsökväg
• ACS-URL:n och Entity ID som konfigurerats i din IdP matchar SnapOtters värden exakt (schema, värd, port, sökväg)

Saknade attribut

Om användarnamn eller e-postadresser är tomma efter inloggning kanske din IdP inte skickar de förväntade attributen. Kontrollera:

• Din IdP är konfigurerad att släppa ett email-attribut (eller vad SAML_EMAIL_ATTRIBUTE är satt till)
• Om du använder SAML_USERNAME_ATTRIBUTE, verifiera att det attributet ingår i assertionen
• Vissa IdP:er kräver uttrycklig attributmappningskonfiguration innan de släpper claims

Klockavvikelse

SAML-assertions inkluderar tidsstämpelvillkor (NotBefore, NotOnOrAfter). Om din serverklocka och IdP-klockan inte är synkroniserade misslyckas assertion-valideringen. Kör NTP på båda maskinerna för att hålla klockorna i linje.

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

Denna varning visas i serverloggarna när SAML_ENABLED=true men licensen inte inkluderar funktionen saml_sso. Verifiera din licensnyckel och plan. Funktionen saml_sso är tillgänglig på team- och enterprise-planer.

Inloggning omdirigerar tillbaka med fel

Om ett klick på SAML-inloggningsknappen omdirigerar tillbaka till inloggningssidan med ett fel, kontrollera serverloggarna för detaljer. Vanliga orsaker:

• IdP:ns SSO-URL är onåbar från servern
• IdP:n avvisade autentiseringsbegäran (kontrollera IdP:ns granskningsloggar)
• IdP:n returnerade ett osignerat svar (SnapOtter kräver att både svaret och assertionen är signerade)