# Single sign-on (SAML)

> Fai accedere il tuo team a intoCHAT con il tuo provider di identità tramite SAML 2.0: configurazione per Okta, Microsoft Entra ID e Google Workspace, verifica dei domini, ingresso automatico nel team, SSO obbligatorio, due fattori e risoluzione dei problemi. Piano Enterprise.

Il single sign-on (SSO) permette alle persone della tua azienda di accedere a intoCHAT con il vostro provider di identità (IdP), come Okta, Microsoft Entra ID (in precedenza Azure AD) o Google Workspace, invece che con una password intoCHAT separata. intoCHAT funziona con qualsiasi IdP che supporti SAML 2.0.

> Il single sign-on fa parte del piano **Enterprise**. Con gli altri piani, **Settings**, **Single sign-on** lo spiega e non si può configurare nulla. Vedi [Piani e limiti](/it/docs/plans-and-limits).

## Come funziona

- Tu, il proprietario dell'account, colleghi il tuo IdP in **Settings**, **Single sign-on** e verifichi i domini email che usa la tua azienda, come `acme.com`.
- Nella pagina di accesso, le persone cliccano **Accedi con SSO**, inseriscono la loro email di lavoro e vengono mandate al tuo IdP. Dopo l'accesso lì, tornano in intoCHAT, nel tuo account.
- Chi accede con SSO per la prima volta entra automaticamente nel tuo [team](/it/docs/team), con il ruolo che scegli tu, se c'è un posto libero. Non serve nessun invito.
- Puoi [imporre l'SSO](#imporre-l-sso) a tutti gli indirizzi dei tuoi domini, così non possono accedere invece con una password o con Google.

Solo il proprietario dell'account può configurare e modificare il single sign-on. Gli Admin possono aprire la pagina e vedere com'è configurato; Editor e Viewer non la vedono. Nemmeno un super admin che consulta il tuo account per l'assistenza può modificarlo.

## Configurare il single sign-on

1. Vai in **Settings**, **Single sign-on** e clicca **Set up single sign-on**. Non cambia nulla per nessuno finché non lo attivi.
2. In **Details for your identity provider**, copia l'**ACS URL**, l'**Entity ID** e il **Metadata URL**. Con questi dati crea un'app SAML nel tuo IdP: vedi [Okta](#okta), [Microsoft Entra ID](#microsoft-entra-id) o [Google Workspace](#google-workspace).
3. In **Identity provider**, incolla l'XML dei metadati del tuo IdP, oppure scegli **Enter manually** e inserisci il suo entity ID, l'URL di accesso (SSO URL) e il certificato di firma. Clicca **Save identity provider**.
4. In **Domains**, aggiungi i tuoi domini email e [verificali](#verificare-i-domini).
5. Scegli il **Role for new members**: Viewer, Editor o Admin.
6. Clicca **Test sign-in** per controllare che il tuo IdP e intoCHAT si capiscano. Vedi [Accesso di prova](#accesso-di-prova).
7. Attiva **Enabled**.

**Enabled** si può attivare solo dopo aver salvato l'entity ID dell'IdP, l'URL di accesso e un certificato valido, e dopo aver verificato almeno un dominio. Fino ad allora, il riquadro **Status** elenca cosa manca.

### Cosa deve inviare il tuo IdP

- **L'indirizzo email della persona** come NameID (formato "EmailAddress" o "Unspecified"), oppure in un attributo chiamato `email`. intoCHAT lo usa per trovare o aggiungere la persona.
- **Un'asserzione firmata.** intoCHAT rifiuta una risposta la cui asserzione non è firmata con il certificato che hai salvato, anche se la risposta che la contiene è firmata.
- **Il nome della persona** (facoltativo) in un attributo chiamato `displayName`, oppure `firstName` e `lastName`. Viene usato quando qualcuno entra per la prima volta.

intoCHAT non firma le sue richieste e non richiede asserzioni cifrate, quindi non devi caricare nessun certificato intoCHAT nel tuo IdP. Il certificato che incolli è il certificato pubblico di firma del tuo IdP. Non incollare mai una chiave privata: intoCHAT la rifiuta.

## Okta

1. Nella Okta Admin Console, vai in **Applications**, **Applications**, clicca **Create App Integration**, scegli **SAML 2.0** e clicca **Next**.
2. Dai un nome all'app, per esempio intoCHAT, e clicca **Next**.
3. Imposta **Single sign-on URL** sull'**ACS URL** di intoCHAT, e lascia selezionato **Use this for Recipient URL and Destination URL**.
4. Imposta **Audience URI (SP Entity ID)** sull'**Entity ID** di intoCHAT.
5. Imposta **Name ID format** su **EmailAddress** e **Application username** su **Email**.
6. Facoltativo: in **Attribute Statements**, aggiungi `email` con il valore `user.email`, e `displayName` con `user.displayName`.
7. Clicca **Next**, poi **Finish**.
8. Nella scheda **Sign On** dell'app, copia il **Metadata URL** e aprilo, oppure clicca **View SAML setup instructions**. Incolla l'XML dei metadati in intoCHAT, in **Identity provider**.
9. Nella scheda **Assignments**, assegna le persone o i gruppi che devono usare intoCHAT.

Okta firma l'asserzione per impostazione predefinita. Lascia **Assertion Signature** su **Signed**.

## Microsoft Entra ID

1. Nell'interfaccia di amministrazione di Microsoft Entra, vai in **Enterprise applications**, clicca **New application**, poi **Create your own application**. Dagli un nome, scegli **Integrate any other application you don't find in the gallery (Non-gallery)** e clicca **Create**.
2. Apri **Single sign-on** e scegli **SAML**.
3. In **Basic SAML Configuration**, clicca **Edit**. Imposta **Identifier (Entity ID)** sull'**Entity ID** di intoCHAT e **Reply URL (Assertion Consumer Service URL)** sull'**ACS URL**. Lascia vuoti **Sign on URL** e **Relay State**. Salva.
4. In **Attributes & Claims**, controlla che **Unique User Identifier (Name ID)** sia `user.mail` (oppure `user.userprincipalname`, se corrisponde all'indirizzo email di ogni persona). Entra invia l'email anche nella sua attestazione `emailaddress`, che intoCHAT legge.
5. In **SAML Certificates**, scarica **Federation Metadata XML** e incollane il contenuto in intoCHAT, in **Identity provider**.
6. In **Users and groups**, aggiungi le persone o i gruppi che devono usare intoCHAT.

Entra firma l'asserzione per impostazione predefinita (**Signing Option**: "Sign SAML assertion"). Se la cambi, scegli "Sign SAML response and assertion", non solo "Sign SAML response".

## Google Workspace

1. Nella Console di amministrazione Google, vai in **Apps**, **Web and mobile apps**, clicca **Add app** e scegli **Add custom SAML app**.
2. Dai un nome all'app, per esempio intoCHAT, e clicca **Continue**.
3. Clicca **Download Metadata** per salvare i metadati dell'IdP, poi clicca **Continue**. Incolla il contenuto del file in intoCHAT, in **Identity provider**.
4. Imposta **ACS URL** sull'**ACS URL** di intoCHAT ed **Entity ID** sull'**Entity ID**. **Signed response** può restare selezionato o no: l'asserzione è firmata in ogni caso.
5. Imposta **Name ID format** su **EMAIL** e **Name ID** su **Basic Information**, **Primary email**. Clicca **Continue**.
6. Facoltativo: in **Attribute mapping**, associa **Primary email** a `email`. Clicca **Finish**.
7. Apri **User access** dell'app e impostalo su **ON for everyone**, oppure sulle unità organizzative che devono usare intoCHAT.

## Verificare i domini

Il single sign-on funziona solo per gli indirizzi email dei domini che hai verificato. La verifica dimostra che il dominio appartiene alla tua azienda, così nessun altro può far entrare nel proprio account le persone di quel dominio.

1. In **Domains**, inserisci un dominio, come `acme.com`, e clicca **Add domain**. Inserisci solo il dominio: niente `https://`, niente `@`. I sottodomini come `mail.acme.com` sono domini separati.
2. Aggiungi il record TXT indicato, `intochat-verification=…`, presso il tuo provider DNS, sul dominio stesso (host `@` presso la maggior parte dei provider).
3. Clicca **Verify**. Il dominio mostra **Verified** quando intoCHAT trova il record.

Le modifiche DNS possono richiedere qualche minuto, a volte fino a 48 ore, per essere visibili ovunque. Se il record non viene ancora trovato, aspetta e clicca di nuovo **Verify**. I controlli sono limitati a 20 ogni 10 minuti per account.

- Un dominio può essere verificato per un solo account intoCHAT. Se un altro account l'ha già verificato, l'aggiunta viene rifiutata.
- Un dominio solo aggiunto (in attesa) non ha alcun effetto. Anche un altro account può avere lo stesso dominio in attesa: lo tiene chi lo verifica per primo.
- Una volta verificato, un dominio resta verificato. Dopo puoi rimuovere il record TXT, ma lasciarlo non fa danni.
- Per rimuovere un dominio, clicca l'icona del cestino accanto. Se rimuovi l'ultimo dominio verificato, il single sign-on si disattiva.

## Accedere con SSO

1. Nella pagina di accesso, clicca **Accedi con SSO**.
2. Inserisci la tua email di lavoro e clicca **Continua**.
3. Accedi al tuo IdP, se non l'hai già fatto.
4. Torni in intoCHAT e lavori nell'account della tua azienda.

L'accesso parte sempre da intoCHAT. Partire dal riquadro di intoCHAT nella dashboard delle app del tuo IdP (accesso avviato dall'IdP) non è supportato e mostra "Il single sign-on non ha funzionato". Un accesso di questo tipo non si può collegare a un accesso che qualcuno ha avviato nel proprio browser, ed è proprio questo collegamento che impedisce di riutilizzare una risposta o di infilarla nel browser di qualcun altro. In Okta e Google Workspace puoi nascondere il riquadro agli utenti.

### Chi può entrare

Quando il tuo IdP comunica chi ha effettuato l'accesso, intoCHAT controlla l'indirizzo email:

- **Il suo dominio deve essere verificato** per il tuo account, per tutti, te e i membri esistenti compresi. Un indirizzo di qualsiasi altro dominio viene rifiutato con un messaggio che dice che il dominio non è verificato.
- **Tu, il proprietario**, accedi al tuo account.
- **Un membro del tuo team** accede con il suo ruolo attuale.
- **Chi ha un invito in sospeso** entra con il ruolo dell'invito, che viene accettato.
- **Chiunque altro** entra nel tuo team con il **Role for new members**. Se non ha ancora un login intoCHAT, gliene viene creato uno, senza password. Se ce l'ha già (con un proprio account), lo mantiene e diventa anche membro del tuo.

Maiuscole e minuscole nell'indirizzo email non contano. I super admin (lo staff di intoCHAT) non possono accedere tramite SSO.

### Posti

Chi entra tramite SSO occupa un posto, come un membro invitato. Enterprise include posti illimitati. Se il tuo account non ha più posti, per esempio dopo un cambio di piano, chi non fa ancora parte del tuo team viene rifiutato con "L'account intoCHAT della tua organizzazione non ha più posti per nuovi membri"; i membri attuali continuano ad accedere.

### Ruoli e rimozione delle persone

Il **Role for new members** vale solo per chi entra per la prima volta. Puoi cambiare il ruolo di chiunque in seguito in **Settings**, **Team**; l'accesso SSO successivo non lo riporta indietro. Rimuovere qualcuno dal team toglie il suo accesso al tuo account, ma se può ancora accedere al tuo IdP, il suo prossimo accesso SSO lo aggiunge di nuovo con il ruolo predefinito. Per tenere fuori qualcuno, togligli anche l'accesso all'app intoCHAT nel tuo IdP.

## Imporre l'SSO

Attiva **Require SSO for members with these domains** per rendere il single sign-on l'unico modo di entrare per gli indirizzi dei tuoi domini verificati:

- L'accesso con email e password viene rifiutato con "La tua organizzazione richiede il single sign-on per questo indirizzo email", qualunque password venga inserita.
- L'accesso con Google viene rifiutato allo stesso modo.
- **Tu, il proprietario dell'account, non vieni mai rifiutato**, così puoi sempre entrare per sistemare le cose se il tuo IdP ha un problema.
- Chi ha già effettuato l'accesso resta connesso finché non esce o la sua sessione non scade.
- Vale solo mentre il single sign-on è attivo e funzionante (con Enterprise, con un certificato valido).

Imporre l'SSO riguarda tutti quelli che hanno un indirizzo dei tuoi domini verificati, anche chi usa intoCHAT per il proprio account invece che per il tuo.

## Autenticazione a due fattori

L'accesso con SSO non chiede un codice di [autenticazione a due fattori](/it/docs/two-factor) intoCHAT, anche se la persona l'ha attivata. L'autenticazione a più fattori spetta al tuo IdP: imponila lì, per esempio con una policy di accesso di Okta, l'accesso condizionale di Entra o la verifica in due passaggi di Google. L'autenticazione a due fattori vale comunque quando la stessa persona accede con email e password.

## Accesso di prova

**Test sign-in**, nel riquadro **Status**, apre il tuo IdP in una nuova scheda e controlla la sua risposta esattamente come farebbe un accesso reale: firma, destinatario (audience), orari, i tuoi domini. Funziona anche prima di attivare il single sign-on. Una prova non fa mai accedere nessuno e non aggiunge mai nessuno al tuo team. Quando funziona, la pagina dice "L'accesso di prova ha funzionato" con l'indirizzo inviato dal tuo IdP (in parte nascosto).

Fai la prova con un account del tuo IdP la cui email appartiene a un dominio verificato.

## Eliminare il single sign-on

In **Delete single sign-on**, clicca **Delete single sign-on** e conferma. L'accesso con SSO smette subito di funzionare e i tuoi domini vengono liberati. Chi è entrato tramite SSO resta nel tuo team. Chi non ha una password può accedere con Google, oppure impostare una password con **Password dimenticata?** nella pagina di accesso.

Se il tuo account lascia il piano Enterprise, il collegamento resta ma smette di funzionare finché non torni a Enterprise, e **Require SSO** non vale più.

## Risoluzione dei problemi

- **"Il single sign-on non è configurato per questo indirizzo email."** Il dominio dell'indirizzo non è verificato per un account con il single sign-on attivo, oppure l'account non è più su Enterprise, oppure il certificato del suo IdP è scaduto. Controlla **Settings**, **Single sign-on**.
- **"Il single sign-on non ha funzionato."** intoCHAT ha rifiutato la risposta del tuo IdP. Le cause più comuni:
  - l'ACS URL o l'Entity ID nel tuo IdP non corrispondono esattamente a quelli della pagina di intoCHAT (copiali di nuovo);
  - l'asserzione non è firmata, oppure è firmata con un certificato diverso da quello salvato (dopo che il tuo IdP ha rinnovato il certificato, incolla quello nuovo);
  - l'accesso è partito dalla dashboard delle app dell'IdP invece che da intoCHAT;
  - l'accesso ha richiesto più di 10 minuti, è partito in un altro browser, oppure la pagina è stata ricaricata dopo l'accesso;
  - gli orologi del tuo IdP e di intoCHAT differiscono di più di 2 minuti.
- **"Il tuo provider di identità ti ha autenticato con un indirizzo email di un dominio non verificato."** L'indirizzo inviato dal tuo IdP non appartiene a un dominio verificato. Controlla quale indirizzo invia (NameID o attributo `email`) e verifica quel dominio.
- **"L'account intoCHAT della tua organizzazione non ha più posti per nuovi membri."** Vedi [Posti](#posti).
- **"Questo link di accesso è scaduto o è già stato usato."** L'ultimo passaggio dell'accesso deve avvenire entro un minuto. Ricomincia da **Accedi con SSO**.
- **"Troppi tentativi di accesso dalla tua rete."** Gli accessi SSO sono limitati per indirizzo di rete. Attendi 15 minuti.
- **Il certificato risulta "expired".** Scarica il certificato di firma attuale dal tuo IdP e salvalo in **Identity provider**. Un certificato scaduto blocca il single sign-on.

## Limiti

- Solo SAML 2.0, con l'accesso avviato da intoCHAT. Niente OpenID Connect, niente accesso avviato dall'IdP.
- Un solo provider di identità per account.
- Niente single logout: uscire da intoCHAT non ti fa uscire dal tuo IdP, e viceversa.
- Niente SCIM. Le persone vengono aggiunte al primo accesso; rimuovere qualcuno nel tuo IdP non lo rimuove dal tuo team intoCHAT.
- Le asserzioni cifrate e le richieste firmate non sono supportate.
- I ruoli vengono dall'impostazione **Role for new members**, non dai gruppi dell'IdP.