mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
225 lines
13 KiB
Markdown
225 lines
13 KiB
Markdown
---
|
|
description: "Configura il Single Sign-On SAML 2.0 per SnapOtter. Guide passo passo per Okta, Azure AD / Entra ID, Google Workspace e altri provider di identità SAML."
|
|
i18n_source_hash: 33dfb8b02a22
|
|
i18n_provenance: human
|
|
i18n_output_hash: 0f4f45cf66f7
|
|
---
|
|
|
|
# SAML SSO {#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.
|
|
|
|
::: tip 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 {#prerequisites}
|
|
|
|
- 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 {#quick-start}
|
|
|
|
Aggiungi queste variabili d'ambiente al tuo `docker-compose.yml`:
|
|
|
|
```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
|
|
```
|
|
|
|
Riavvia il container. Un pulsante "Accedi con SAML" (o l'etichetta impostata da `SAML_PROVIDER_NAME`) appare nella pagina di login.
|
|
|
|
## Riferimento della configurazione {#configuration-reference}
|
|
|
|
| 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.
|
|
|
|
::: details 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 {#sp-metadata-and-urls}
|
|
|
|
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 {#provider-setup}
|
|
|
|
### Okta {#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 {#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 {#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 {#generic-saml-2-0-idp}
|
|
|
|
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 {#user-provisioning}
|
|
|
|
### Creazione automatica {#auto-create}
|
|
|
|
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 {#auto-link}
|
|
|
|
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 {#attribute-mapping}
|
|
|
|
| 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 {#sso-enforcement}
|
|
|
|
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 {#using-saml-alongside-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 {#troubleshooting}
|
|
|
|
### Validazione dell'asserzione non riuscita {#assertion-validation-failed}
|
|
|
|
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 {#missing-attributes}
|
|
|
|
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 {#clock-skew}
|
|
|
|
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" {#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 {#login-redirects-back-with-error}
|
|
|
|
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)
|