# Connessioni

Consentire l'accesso tramite un provider di identità esterno (OIDC, SAML, Microsoft Entra, social), con collegamento degli account e creazione JIT.

> **Nota sul piano:** i provider social (come Google, Apple, GitHub e molti altri) fanno parte di ogni piano. I provider enterprise (OIDC/SAML generico, Microsoft Entra, Okta, Auth0, Ping Identity, Keycloak, OneLogin, JumpCloud, DATEV, gli aggregatori di identità elettroniche Criipto e Signicat e l'eID tedesca) richiedono la funzionalità **enterprise identity brokering**, inclusa nel piano Advanced e superiori (e in Trial).

Una **connessione** consente agli utenti di accedere con un Identity Provider *esterno*, ossia un'opzione "Sign in with…" nella schermata di accesso. La piattaforma delega l'autenticazione al provider, riceve indietro il profilo dell'utente e lo collega a un account esistente oppure ne crea uno nuovo. In termini di protocollo, la piattaforma agisce da Relying Party (OIDC) o da Service Provider (SAML); il provider esterno è l'Identity Provider.

Le connessioni si gestiscono in **Integrazioni → Connessioni** nella Admin Console.

## Provider disponibili

Le connessioni si suddividono in tre gruppi.

**Generici** (basati su standard, configurabili più di una volta):

| Provider | Protocollo | Utilizzo tipico |
|---|---|---|
| **OpenID Connect (generic)** | OIDC | Qualsiasi Identity Provider OIDC conforme agli standard. |
| **SAML 2.0 (generic)** | SAML | Qualsiasi Identity Provider SAML 2.0. |

**Enterprise:**

| Provider | Protocollo | Utilizzo tipico |
|---|---|---|
| **Microsoft Entra** | OIDC | Accesso con un tenant Microsoft Entra (aziendale o scolastico). |
| **Okta** | OIDC | Accesso con un'org Okta Workforce. Richiede il proprio dominio Okta. |
| **Auth0** | OIDC | Accesso con un tenant Auth0. Richiede il proprio dominio Auth0. |
| **Ping Identity (PingOne)** | OIDC | Accesso con un ambiente PingOne. Richiede l'host PingOne e l'environment ID. |
| **Keycloak** | OIDC | Accesso con un realm Keycloak. Richiede l'URL del server e il realm. |
| **OneLogin** | OIDC | Accesso con un account OneLogin. Richiede il proprio dominio OneLogin. |
| **JumpCloud** | OIDC | Accesso con un account JumpCloud. |
| **DATEV** | OIDC | Accesso con un account DATEV (commercialisti e loro clienti). |
| **Criipto** | OIDC | Identità elettroniche europee (MitID, BankID, itsme e altre) tramite un'unica connessione al proprio tenant Criipto. |
| **Signicat** | OIDC | Identità elettroniche europee tramite un'unica connessione al proprio account Signicat. |
| **German eID (Online-Ausweis)** | OIDC | Accesso con la carta d'identità tedesca tramite AusweisIDent. |

**Social e consumer** (ciascuno configurabile una sola volta): Amazon, Apple, Basecamp, Bitbucket, Box, DigitalOcean, Discord, Docusign, Dropbox, Facebook, Figma, Fitbit, FreshBooks, GitHub, GitLab, Google, Hugging Face, Intuit (QuickBooks), Kakao, Klarna, LINE, LinkedIn, Microsoft account, netID, PayPal, Salesforce, Slack, SoundCloud, Spotify, Strava, TikTok, Twitch, Vimeo, WordPress.com, X, Xero e Yahoo.

Le connessioni OIDC e SAML generiche possono essere configurate più di una volta (per diversi provider); ogni provider denominato si configura una sola volta. Nuovi provider vengono aggiunti nel tempo, quindi l'elenco autorevole è la schermata di creazione.

L'elenco delle connessioni mostra un banner quando si raggiunge il numero massimo di connessioni previsto dal proprio piano; per aggiungerne un'altra occorre svuotare o rimuovere una connessione.

[Image: L'elenco delle connessioni con tre Identity Provider configurati]

## Aggiungere una connessione

1. Nella pagina delle connessioni scegliere **Crea connessione** e selezionare un provider.
2. Esaminare i **prerequisiti** indicati dalla connessione, per esempio la registrazione di un'applicazione presso il provider esterno per ottenere un client ID e un secret, quindi confermare.
3. Compilare il modulo di configurazione (vedere di seguito).
4. Salvare. Le nuove connessioni nascono **disabilitate**; una connessione va abilitata quando deve comparire nella schermata di accesso.

### Campi di configurazione

Ogni connessione necessita di un **Nome** e di una **Directory** di destinazione, ossia la directory in cui vengono collocati i nuovi utenti creati tramite questa connessione. Vedere [Directory utenti](https://dts-identity.com/it/docs/directories/user-directories.md).

I campi specifici del protocollo sono:

- **Generic OIDC**: l'URL di discovery (configurazione) del provider, un client ID, un client secret e gli scope da richiedere (per impostazione predefinita `openid profile email`). L'URL di discovery viene letto ogni volta, così la connessione recepisce gli endpoint e le chiavi del provider senza doverli reinserire.
- **Microsoft Entra**: un client ID, un client secret e il **tenant ID** (oppure `common` per il multi-tenant). Gli endpoint del provider provengono dal documento di discovery Microsoft per quel tenant.
- **Okta**: un client ID, un client secret e il proprio **dominio Okta** (per esempio `acme.okta.com`, un'org di preview oppure un dominio personalizzato). Creare una OIDC Web Application nella Okta Admin Console e assegnarla agli utenti che devono accedere.
- **Auth0**: un client ID, un client secret e il proprio **dominio Auth0** (per esempio `acme.eu.auth0.com` oppure un dominio personalizzato). Creare una Regular Web Application nella Auth0 Dashboard.
- **Ping Identity (PingOne)**: un client ID, un client secret, l'**host PingOne** (l'host regionale, per esempio `auth.pingone.com` o `auth.pingone.eu`, oppure un dominio personalizzato) e l'**environment ID**.
- **Keycloak**: un client ID, un client secret, l'**URL del server** e il **realm**. Su Keycloak 16 e versioni precedenti, includere il percorso base `/auth` nell'URL del server. Attivare l'autenticazione del client, così il client è riservato.
- **OneLogin**: un client ID, un client secret e il proprio **dominio OneLogin** (per esempio `acme.onelogin.com`). Impostare su **POST** il metodo di autenticazione del token endpoint dell'applicazione.
- **JumpCloud**: un client ID e un client secret di un'applicazione OIDC personalizzata. Impostarne il tipo di autenticazione del client su **Client Secret Post**.
- **DATEV**: un client ID e un client secret di un'app nel DATEV Developer Portal, con sottoscrizione al prodotto "Login with DATEV". L'accesso in produzione segue una verifica tecnica.
- **Criipto**: il dominio del proprio tenant Criipto (per esempio `acme.criipto.id` oppure un dominio personalizzato), un client ID, un client secret e l'identità elettronica da utilizzare. Poiché l'identità elettronica è fissa per ciascuna connessione, occorre aggiungere una connessione per ogni identità elettronica da offrire.
- **Signicat**: il dominio del proprio account Signicat (per esempio `acme.signicat.com`), un client ID, un client secret e l'identità elettronica da utilizzare. Aggiungere una connessione per ogni identità elettronica.
- **German eID (Online-Ausweis)**: l'ambiente (produzione o riferimento) e un client ID e un client secret di AusweisIDent. AusweisIDent gestisce il server eID e detiene il certificato di autorizzazione, quindi l'integrazione avviene tramite OIDC standard.
- **Kakao**: una REST API key (client ID) e un client secret. Nella console Kakao Developers occorre abilitare Kakao Login, attivare OpenID Connect nelle impostazioni avanzate (necessario per ricevere un ID token) e configurare le voci di consenso. L'accesso all'indirizzo email richiede una Kakao Business App.
- **netID**: un client ID e un client secret di un servizio registrato nel portale per sviluppatori netID. Un nuovo servizio nasce in sandbox per utenti di test in allowlist; per l'uso in produzione occorre richiederne il rilascio.
- **Intuit (QuickBooks)**: un client ID e un client secret di un'app nel portale Intuit Developer. Le chiavi di produzione vengono rilasciate dopo che Intuit ha completato la valutazione dell'app.
- **La maggior parte dei provider social**: un client ID (a volte indicato in altro modo, per esempio il client ID di Slack, la key di Bitbucket, l'application ID di GitLab, l'integration key di Docusign) e il secret corrispondente. Per i nomi esatti dei campi occorre seguire la guida di configurazione di ciascun provider.
- **Provider con host o area geografica**: Salesforce, GitLab e Docusign aggiungono un campo **host** (per esempio un My Domain Salesforce, un'istanza GitLab autogestita oppure l'host di produzione o di sviluppo di Docusign), così la connessione punta all'istanza corretta.
- **Apple**: un Services ID (il client ID), il proprio team ID, il key ID e il contenuto della chiave privata `.p8` scaricata da Apple. La chiave privata viene memorizzata cifrata e non viene mai mostrata di nuovo; il client secret richiesto da Apple viene generato automaticamente a partire da essa.
- **Generic SAML**: l'URL di entry point (accesso) del provider, il suo Entity ID e il suo certificato di firma in formato PEM, inseriti direttamente. L'URL di callback (ACS) e l'Entity ID della piattaforma sono indicati nella guida di configurazione della connessione, per essere registrati sul lato del provider.

I secret e le chiavi private si inseriscono in campi che restano vuoti quando si modifica una connessione esistente: lasciando vuoto un campo secret si conserva il valore memorizzato. I secret non vengono mai mostrati di nuovo in chiaro né scritti nei log.

Durante la configurazione della connessione, ogni guida indica anche l'**URL di callback** da registrare presso il provider, affinché quest'ultimo instradi la risposta di accesso verso questa piattaforma.

### Routing per dominio email (Home Realm Discovery)

Attivando **Home realm discovery** su una connessione e indicando uno o più **Domini email**, un utente che immette un indirizzo email con un dominio corrispondente viene inviato direttamente a quel provider anziché alla schermata della password, così nessuno deve scegliere il pulsante "Sign in with…" corretto. I domini si immettono come elenco separato da virgole (per esempio `acme.com, acme.co.uk`).

- Una connessione con domini email impostati **non viene mostrata come pulsante** nella pagina di accesso; vi si arriva soltanto tramite il routing per dominio (oppure tramite un link diretto alla connessione). Ciò mantiene ordinata la schermata di accesso quando sono configurati più provider enterprise.
- Un dominio può essere assegnato a **una sola** connessione; il salvataggio di una seconda connessione con lo stesso dominio viene rifiutato.
- Gli utenti il cui dominio email non è instradato, e gli utenti che accedono con un nome utente, proseguono verso la normale schermata della password.
- L'email viene trasmessa a un provider OIDC come `login_hint`, così il provider può precompilarla e l'utente non deve immetterla una seconda volta. I provider SAML non la ricevono (una SAML Request di accesso non può trasportarla in modo affidabile).
- Quando un'applicazione avvia l'accesso con un indirizzo email noto (un `login_hint` OIDC) in un dominio instradato, l'utente viene inviato direttamente al provider, senza vedere prima la schermata di accesso.
- Disattivando Home realm discovery (oppure svuotandone i domini), il pulsante della connessione ricompare nella pagina di accesso.

Se un provider instradato è temporaneamente configurato in modo errato ed è necessario raggiungere la schermata della password per un account di quel dominio, aggiungere `?noHrd=1` all'URL di accesso per saltare il routing in quella singola visita.

### Perché registrare una propria app presso il provider

Per ogni connessione (un provider social come GitHub o LinkedIn, oppure un provider enterprise come Okta o Microsoft Entra) si registra un'applicazione OAuth *presso il provider* e se ne indicano qui il client ID e il secret, anziché utilizzarne una condivisa. Ciò è voluto:

- La schermata di consenso mostra il **proprio** nome e il **proprio** logo, non uno generico.
- L'app richiede esattamente gli **scope necessari**.
- Il callback viene instradato verso il **proprio dominio**, così la disconnessione e lo step-up MFA si comportano correttamente.

La schermata dei prerequisiti della connessione elenca ciò che occorre registrare prima di iniziare.

## Collegamento degli account

Quando un utente ritorna tramite una connessione, la piattaforma lo riconosce dall'identificatore stabile fornito dal provider (non dall'email), lo autentica sul proprio account collegato e ne aggiorna nome e immagine a partire dal provider.

Per prevenire l'appropriazione di account, se il provider comunica un indirizzo email che appartiene già a un account **diverso** non collegato a questa connessione, l'accesso viene **rifiutato** anziché unire silenziosamente i due: non esiste un passaggio amministrativo di "unione degli account", e un'email in arrivo (soprattutto se non verificata) non si appropria mai di un account esistente. L'email della connessione viene adottata su un account solo quando la connessione è **attendibile**, il provider dichiara l'email come verificata e il dominio dell'email non è riservato a un'altra directory (vedere la riserva dei domini di posta in [Directory utenti](https://dts-identity.com/it/docs/directories/user-directories.md)).

## Creazione just-in-time degli utenti

Quando qualcuno accede per la prima volta tramite una connessione e non esiste alcun account corrispondente, la piattaforma ne crea uno **just in time**:

- Il nuovo utente viene collocato nella **Directory** configurata sulla connessione.
- Il suo profilo (nome, email, immagine) viene ripreso dal provider.
- Non ha una password e accede soltanto tramite la stessa connessione.

Il modo in cui il nuovo account viene attivato dipende dall'impostazione **Origine attendibile**:

- Se la connessione è contrassegnata come **attendibile** *e* il provider dichiara l'email come verificata, l'account viene attivato immediatamente.
- Altrimenti l'utente riceve un'email di attivazione e deve verificare il proprio indirizzo prima che l'account diventi attivo.

I provider social sono attendibili per impostazione predefinita; le connessioni OIDC e SAML generiche non lo sono, perché conviene fidarsi di un claim email solo se proviene da un provider che si controlla o che è stato verificato.

### Provider senza indirizzo email

Alcuni provider non rilasciano un indirizzo email (per esempio X, Strava, Fitbit, SoundCloud, Vimeo e TikTok). Anche le connessioni di identità elettronica (Criipto, Signicat e l'eID tedesca) restituiscono un nome verificato e un identificatore nazionale anziché un'email. L'accesso tramite uno di questi provider funziona comunque e crea comunque un account, ma tale account non ha un'email: non viene inviata alcuna email di attivazione e non è possibile abbinarlo a un account esistente tramite l'email. L'utente può aggiungere e verificare un'email in un secondo momento dal proprio portale dell'account, il che abilita anche il recupero basato sull'email ed eventuali opzioni di autenticazione a più fattori basate sull'email.

Alcuni provider restituiscono un'email che non verificano (per esempio Spotify). Tale email viene memorizzata sul nuovo account, ma è trattata come non verificata e non viene mai adottata su un altro account esistente, quindi l'account segue comunque le normali regole di verifica.

### Apple

Apple restituisce il nome dell'utente **solo al primissimo accesso**, quindi un utente Apple che ritorna mantiene il nome acquisito in quell'occasione. Gli utenti che scelgono l'opzione **Hide My Email** di Apple accedono con un indirizzo di inoltro privato, e questo funziona normalmente. La chiave privata `.p8` immessa viene memorizzata cifrata e utilizzata soltanto per generare il client secret di breve durata richiesto da Apple.

## Impostazioni per connessione

| Impostazione | Effetto |
|---|---|
| **Nome** | L'etichetta mostrata nella Admin Console e nell'audit log. |
| **Directory** | Dove vengono creati gli utenti just-in-time. |
| **Home realm discovery** | Se attiva, i domini email instradati verso questa connessione. Un utente che immette un'email con uno di questi domini viene inviato direttamente a questo provider, e la connessione non compare come pulsante nella pagina di accesso. Un dominio può appartenere a una sola connessione. |
| **Origine attendibile** | Governa l'attivazione automatica e l'eventuale adozione dell'email del provider. |
| **Abilitato** | Solo le connessioni abilitate compaiono nella schermata di accesso. |

È possibile disabilitare una connessione per toglierla dalla schermata di accesso senza eliminarla, oppure eliminarla del tutto. Entrambe le azioni richiedono una conferma tramite la digitazione del nome della connessione.

## Riferimento

| Termine | Significato |
|---|---|
| Connessione | Una delega dell'accesso a un Identity Provider esterno. |
| Collegamento degli account | L'abbinamento di un'identità federata che ritorna a un account esistente. |
| Creazione just-in-time (JIT) | La creazione di un nuovo account al primo accesso federato di un utente. |
| Origine attendibile | Una connessione il cui claim di email verificata viene ritenuto affidabile dalla piattaforma per l'attivazione automatica. |
| Home Realm Discovery | L'instradamento automatico di un accesso verso una connessione, in base al dominio email immesso dall'utente. |

## Risoluzione dei problemi

- **Il provider restituisce un errore nel callback.** La causa più frequente è un URL di redirect (callback) non registrato presso il provider esterno, oppure un client ID o secret non corrispondente. Registrare l'URL di callback esatto mostrato al momento della creazione della connessione e ricontrollare le credenziali.
- **Il token exchange non riesce con un errore `invalid_client`.** Alcuni provider (per esempio OneLogin e JumpCloud) impostano per impostazione predefinita su Basic il metodo di autenticazione del token endpoint dell'applicazione. Impostarlo su **POST** (client secret post) nelle impostazioni dell'applicazione presso il provider.
- **Gli utenti con un determinato dominio email vengono inviati direttamente a un provider esterno.** Quel dominio è assegnato ai domini di posta di una connessione, il che attiva il routing per dominio (Home Realm Discovery). Per interrompere il routing occorre rimuovere il dominio dalla connessione. Per raggiungere una sola volta la schermata della password (per esempio quando il provider è configurato in modo errato), aggiungere `?noHrd=1` all'URL di accesso.
- **L'accesso Kakao non riesce oppure non restituisce alcun ID token.** Kakao emette un ID token solo quando OpenID Connect è attivato nelle impostazioni avanzate di Kakao Login dell'app. Anche una voce di consenso mancante interrompe l'accesso; configurare le voci di consenso richieste (nickname, immagine del profilo) nella console Kakao.
- **Un utente che ritorna approda su un account nuovo e vuoto.** Il collegamento degli account abbina un'identità federata a un account esistente tramite l'email verificata. Se il provider non restituisce un'email verificata, oppure se l'email differisce da quella memorizzata, non viene trovata alcuna corrispondenza e viene creato un account separato. Verificare che il provider rilasci un claim di email verificata.
- **Il primo accesso tramite una connessione viene rifiutato con un errore di dominio.** Il dominio dell'email è riservato a un'altra directory. Un dominio elencato su una directory non può essere rivendicato da utenti creati altrove, incluso l'accesso federato just-in-time. Occorre spostare la riserva oppure utilizzare un indirizzo in un dominio non riservato.
- **Un utente federato viene creato ma resta inattivo.** I nuovi account vengono attivati automaticamente soltanto per una connessione attendibile che restituisce un'email verificata. Per le altre connessioni l'account segue le normali regole di verifica e di ciclo di vita.

Vedere anche il [glossario](https://dts-identity.com/it/docs/reference/glossary.md).
