SAML SSO

SnapOtter supporta SAML 2.0 per il single sign-on. Gli utenti possono accedere tramite un provider di identità esterno (Okta, Azure AD / Entra ID, Google Workspace o qualsiasi IdP SAML 2.0 standard) invece dell'autenticazione locale con username/password.

Funzionalità enterprise

SAML SSO richiede una licenza team o enterprise con la funzionalità saml_sso. Se SAML_ENABLED=true è impostato senza una licenza valida, le route SAML vengono ignorate silenziosamente e viene registrato un avviso.

Prerequisiti

• Un'istanza di SnapOtter in esecuzione, raggiungibile a un URL pubblico
• EXTERNAL_URL impostato su quell'URL pubblico (es. https://photos.example.com)
• Una chiave di licenza team o enterprise con la funzionalità saml_sso
• Accesso amministrativo al tuo provider di identità SAML

Avvio rapido

Aggiungi queste variabili d'ambiente al tuo 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

Riavvia il container. Un pulsante "Accedi con SAML" (o l'etichetta impostata da SAML_PROVIDER_NAME) appare nella pagina di login.

Riferimento della configurazione

Variabile	Predefinito	Descrizione
SAML_ENABLED	false	Abilita il login SAML.
SAML_IDP_SSO_URL		URL dell'endpoint SSO dell'IdP. Obbligatorio quando SAML è abilitato.
SAML_IDP_CERTIFICATE		Certificato di firma X.509 dell'IdP in formato PEM (il testo del certificato stesso, non un percorso di file). Obbligatorio quando SAML è abilitato.
EXTERNAL_URL		L'URL pubblico su cui SnapOtter è raggiungibile. Obbligatorio quando SAML è abilitato.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	SP Entity ID / Audience URI inviato all'IdP.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	URL dell'Assertion Consumer Service (ACS).
SAML_AUTO_CREATE_USERS	true	Crea automaticamente un account utente locale al primo login SAML.
SAML_AUTO_LINK_USERS	false	Collega un'identità SAML a un utente locale esistente se l'indirizzo email corrisponde.
SAML_DEFAULT_ROLE	user	Ruolo assegnato agli utenti SAML creati automaticamente. Uno tra admin, editor o user.
SAML_PROVIDER_NAME		Etichetta visualizzata per il pulsante di login SAML sul frontend (es. "Okta", "Azure AD"). Se vuoto, il pulsante riporta "SAML".
SAML_USERNAME_ATTRIBUTE		Attributo dell'asserzione SAML usato come username. Se vuoto, ricade sulla parte locale dell'email, poi sul NameID.
SAML_EMAIL_ATTRIBUTE	email	Attributo dell'asserzione SAML usato come indirizzo email dell'utente.

Il server rifiuta di avviarsi se SAML_ENABLED=true e una qualsiasi delle tre variabili obbligatorie (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL) manca.

Note sulla sicurezza

Sia wantAuthnResponseSigned che wantAssertionsSigned sono impostati in modo fisso su true. SnapOtter rifiuta le risposte SAML non firmate o firmate in modo improprio. Le asserzioni provenienti da un IdP attendibile sono trattate come email verificate.

È supportato solo il login avviato dall'SP. SnapOtter non supporta il login avviato dall'IdP (non sollecitato) né il Single Logout (SLO). La disconnessione da SnapOtter non disconnette l'utente dall'IdP.

Metadati e URL dell'SP

Il tuo IdP ha bisogno di tre valori da SnapOtter:

Campo	Valore
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

Ad esempio, se EXTERNAL_URL è https://photos.example.com:

• ACS URL: https://photos.example.com/api/auth/saml/callback
• Entity ID: https://photos.example.com/api/auth/saml/metadata
• Endpoint dei metadati: https://photos.example.com/api/auth/saml/metadata (restituisce XML)

Alcuni IdP possono importare direttamente l'URL dei metadati dell'SP, che compila automaticamente l'ACS URL e l'Entity ID.

Configurazione del provider

Okta

1. Nella console di amministrazione Okta, vai su Applications > Create App Integration.
2. Seleziona SAML 2.0 e fai clic su Next.
3. Imposta un nome (es. "SnapOtter") e fai clic su Next.
4. Configura le impostazioni SAML:
   • Single sign-on URL: il tuo ACS URL (es. https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): il tuo Entity ID (es. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. In Attribute Statements, aggiungi email mappato su user.email.
6. Fai clic su Next, poi su Finish.
7. Vai alla scheda Sign On, fai clic su View SAML setup instructions e copia:
   • Identity Provider Single Sign-On URL in SAML_IDP_SSO_URL
   • X.509 Certificate in SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. Nel portale Azure, vai su Microsoft Entra ID > Enterprise applications > New application.
2. Fai clic su Create your own application, chiamala "SnapOtter" e seleziona Integrate any other application you don't find in the gallery.
3. Vai su Single sign-on > SAML e fai clic su Edit nella sezione Basic SAML Configuration:
   • Identifier (Entity ID): il tuo Entity ID (es. https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): il tuo ACS URL (es. https://photos.example.com/api/auth/saml/callback)
4. In SAML Certificates, scarica il Certificate (Base64).
5. In Set up SnapOtter, copia il Login URL.
6. Imposta SAML_IDP_SSO_URL sul Login URL e SAML_IDP_CERTIFICATE sul contenuto del certificato scaricato.
7. Assegna utenti o gruppi all'applicazione in Users and groups.

Google Workspace

1. Nella console di amministrazione Google, vai su Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Chiama l'app "SnapOtter" e fai clic su Continue.
3. Nella pagina Google Identity Provider details, copia l'SSO URL e scarica il Certificate. Fai clic su Continue.
4. Configura i dettagli del Service Provider:
   • ACS URL: il tuo ACS URL (es. https://photos.example.com/api/auth/saml/callback)
   • Entity ID: il tuo Entity ID (es. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Fai clic su Continue, poi su Finish.
6. Attiva l'app (ON) per le tue unità organizzative.
7. Imposta SAML_IDP_SSO_URL sull'SSO URL del passaggio 3 e SAML_IDP_CERTIFICATE sul contenuto del certificato scaricato.

IdP SAML 2.0 generico

Per qualsiasi provider di identità conforme a SAML 2.0:

1. Crea una nuova applicazione/service provider SAML nel tuo IdP.
2. Imposta l'ACS URL su ${EXTERNAL_URL}/api/auth/saml/callback.
3. Imposta l'Entity ID / Audience su ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Configura l'IdP per inviare l'email dell'utente in un attributo chiamato email (oppure imposta SAML_EMAIL_ATTRIBUTE per corrispondere al nome dell'attributo del tuo IdP).
5. Copia l'IdP SSO URL e il certificato di firma in SAML_IDP_SSO_URL e SAML_IDP_CERTIFICATE.

Provisioning degli utenti

Creazione automatica

Quando SAML_AUTO_CREATE_USERS è true (l'impostazione predefinita), un account utente locale viene creato la prima volta che qualcuno accede tramite SAML. Il ruolo è impostato su SAML_DEFAULT_ROLE.

Lo username è derivato in questo ordine:

1. Il valore dell'attributo dell'asserzione specificato da SAML_USERNAME_ATTRIBUTE (se impostato e presente)
2. La parte locale dell'indirizzo email (tutto ciò che precede @)
3. Il NameID SAML

Se si verifica una collisione di username, viene aggiunto un suffisso numerico (es. jane diventa jane_2).

Collegamento automatico

Quando SAML_AUTO_LINK_USERS è true, SnapOtter collega un'identità SAML a un account locale esistente se gli indirizzi email corrispondono. Questo è utile quando hai account utente pre-creati e vuoi che inizino a usare l'SSO senza perdere i loro dati.

WARNING

Abilita il collegamento automatico solo se ti fidi del tuo IdP SAML per la verifica degli indirizzi email. Un'email non verificata da un IdP mal configurato potrebbe consentire a qualcuno di impossessarsi dell'account di un altro utente.

Mappatura degli attributi

Campo SnapOtter	Origine	Configurazione
Email	Attributo dell'asserzione	SAML_EMAIL_ATTRIBUTE (predefinito: email)
Username	Attributo dell'asserzione, email o NameID	SAML_USERNAME_ATTRIBUTE (vedi l'ordine di derivazione sopra)
ID esterno	NameID	Sempre il NameID SAML, non configurabile

Applicazione dell'SSO

Se vuoi imporre a tutti gli utenti l'accesso tramite SAML (o OIDC) e bloccare il login locale con password, abilita l'applicazione dell'SSO:

1. Assicurati che la funzionalità enterprise sso_enforcement sia licenziata (disponibile nei piani team ed enterprise).
2. In Admin Settings > Security, attiva SSO Enforcement.
3. Imposta un break-glass username: questo è l'unico account locale che può ancora accedere con una password, per l'accesso di emergenza se l'IdP è irraggiungibile.

Quando l'applicazione dell'SSO è attiva, qualsiasi tentativo di login locale (tranne quello dell'utente break-glass) restituisce un errore 403 con il messaggio "Local password login is disabled. Please use SSO."

TIP

Configura sempre un break-glass username prima di abilitare l'applicazione dell'SSO. Senza di esso, potresti restare bloccato fuori da SnapOtter se il tuo IdP smette di funzionare.

Uso di SAML insieme a OIDC

SAML e OIDC possono essere abilitati contemporaneamente. Quando entrambi sono attivi, la pagina di login mostra pulsanti separati per ciascun provider (etichettati da SAML_PROVIDER_NAME e OIDC_PROVIDER_NAME). Gli utenti possono accedere con l'uno o l'altro metodo.

Entrambi i provider condividono le stesse impostazioni di creazione automatica, collegamento automatico e applicazione dell'SSO in modo indipendente: ciascuno ha le proprie variabili *_AUTO_CREATE_USERS, *_AUTO_LINK_USERS e *_DEFAULT_ROLE.

Risoluzione dei problemi

Validazione dell'asserzione non riuscita

Non è stato possibile verificare la firma della risposta SAML o dell'asserzione. Controlla:

• Il certificato in SAML_IDP_CERTIFICATE corrisponde al certificato di firma corrente nel tuo IdP (i certificati vengono ruotati, quindi controlla la scadenza)
• Il certificato è in formato PEM (inizia con -----BEGIN CERTIFICATE-----)
• Il certificato è il testo completo, non un percorso di file
• L'ACS URL e l'Entity ID configurati nel tuo IdP corrispondono esattamente ai valori di SnapOtter (schema, host, porta, percorso)

Attributi mancanti

Se username o email sono vuoti dopo il login, il tuo IdP potrebbe non inviare gli attributi attesi. Controlla:

• Il tuo IdP è configurato per rilasciare un attributo email (o qualunque valore sia impostato SAML_EMAIL_ATTRIBUTE)
• Se usi SAML_USERNAME_ATTRIBUTE, verifica che quell'attributo sia incluso nell'asserzione
• Alcuni IdP richiedono una configurazione esplicita di mappatura degli attributi prima di rilasciare i claim

Scarto dell'orologio

Le asserzioni SAML includono condizioni temporali (NotBefore, NotOnOrAfter). Se l'orologio del tuo server e quello dell'IdP non sono sincronizzati, la validazione dell'asserzione fallisce. Esegui NTP su entrambe le macchine per mantenere gli orologi allineati.

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

Questo avviso appare nei log del server quando SAML_ENABLED=true ma la licenza non include la funzionalità saml_sso. Verifica la tua chiave di licenza e il piano. La funzionalità saml_sso è disponibile nei piani team ed enterprise.

Il login reindirizza indietro con un errore

Se facendo clic sul pulsante di login SAML vieni reindirizzato alla pagina di login con un errore, controlla i log del server per i dettagli. Cause comuni:

• L'SSO URL dell'IdP è irraggiungibile dal server
• L'IdP ha rifiutato la richiesta di autenticazione (controlla i log di audit dell'IdP)
• L'IdP ha restituito una risposta non firmata (SnapOtter richiede che sia la risposta che l'asserzione siano firmate)