Panoramica
Benvenuti in questo approfondimento su OAuth 2.0, un protocollo di autenticazione potente ma spesso frainteso nell’ecosistema Tulip. In questo articolo ne sveleremo i fondamenti, vi guideremo attraverso i flussi di autenticazione supportati da Tulip, chiariremo la configurazione del vostro connettore iniziale e condivideremo alcuni consigli rapidi per un avvio senza intoppi.
Per informazioni sulla gestione dei token di aggiornamento, sull’amministrazione degli ambiti e del pubblico e sulle configurazioni dei connettori personalizzati da parte di Tulip, consultare la sezione Dettagli tecnici.
Tipi di autenticazione
Tulip supporta tre tipi di autenticazione OAuth 2.0: OAuth 2.0 (account di servizio), OAuth 2.0 (credenziali utente) e OAuth 2.0 (credenziali client). La differenza fondamentale risiede nel modo in cui le credenziali vengono condivise tra gli utenti e nel flusso eseguito in base alle specifiche OAuth. Un elenco completo e una descrizione dei flussi OAuth specifici sono disponibili qui: https://frontegg.com/blog/oauth-flows.
In older Tulip versions, OAuth2.0 (Service Account) was called OAuth2 (Admin), and OAuth2.0 (User Credentials) was called OAuth2 (Operator).
Flusso del codice di autorizzazione:
- OAuth 2.0 (account di servizio): utilizza le credenziali fornite durante il test del connettore per tutti gli utenti di Tulip Player. Ideale per le credenziali condivise all’interno della propria organizzazione. Se le credenziali scadono, è necessaria una nuova autenticazione da parte dell’amministratore.
- OAuth 2.0 (credenziali utente): segmenta l’autenticazione in base all’utente che ha effettuato l’accesso a Tulip Player. Se un utente non si è autenticato o l’autenticazione scade, l’utente viene sottoposto al flusso OAuth all’interno di Tulip Player.
Flusso con credenziali del client:
- OAuth 2.0 (credenziali del client): questo tipo di concessione viene utilizzato da Tulip per ottenere un token di accesso autenticandosi con il server di autorizzazione utilizzando le credenziali del client (ID client e segreto client), in genere per accedere alle risorse per conto proprio piuttosto che per conto di un utente.
Prima di approfondire i dettagli, ti consigliamo di familiarizzare con gli ambienti e di acquisire una visione d’insieme degli host dei connettori e delle loro funzioni.
OAuth 2.0 funge da meccanismo che consente a Tulip (il client) di stabilire la propria identità presso i sistemi aziendali.
Flusso del codice di autorizzazione
:::(Avviso) (Avviso)
Per completare il processo di autenticazione dell’utente, il browser deve consentire i pop-up. Se l’ connector e è configurato con più ambienti, durante l’autenticazione ogni ambiente aprirà una finestra pop-up separata.
Verifica se i pop-up sono abilitati in Chrome:
- Apri Chrome e fai clic sul menu con i tre puntini nell’angolo in alto a destra della finestra.
- Seleziona “Impostazioni” dal menu a tendina.
- Scorri verso il basso e clicca su " Privacy e sicurezza".
- Nella sezione "Privacy e sicurezza", clicca su Impostazioni siti.
- Scorri verso il basso e clicca su " Finestre pop-up e reindirizzamenti".
- Assicurati che l'interruttore sia impostato su "Consenti pop-up" oppure aggiungi manualmente il sito web all'elenco dei siti autorizzati a mostrare pop-up.
Se i pop-up sono bloccati, Chrome visualizzerà una piccola icona nella barra degli indirizzi ogni volta che un pop-up viene bloccato. Puoi cliccare su questa icona per consentire rapidamente i pop-up da Tulip.
:::
L’accesso viene concesso tramite un handshake e Tulip supporta principalmente il flusso del codice di autorizzazione (Authorization Code Flow), il flusso OAuth più comune. Ecco una panoramica sintetica di come si svolge questo flusso:
- L’utente avvia il flusso cliccando sul pulsante “Test” prima di salvare un connettore.
- Tulip comunica con il server di autorizzazione del proprio provider OAuth, condividendo parametri specifici quali l’identità del client, gli ambiti (a cosa si sta tentando di accedere) e altri dettagli rilevanti.
- Il server di autorizzazione richiede all’utente di concedere l’accesso, come illustrato di seguito:
- Una volta ottenuto il consenso dell’utente, il server di autorizzazione genera un codice di autorizzazione e chiude la finestra di autenticazione.
- In possesso del codice di autorizzazione, Tulip richiede in modo sicuro un token contattando l’endpoint del token, fornendo il codice di autorizzazione, l’ID cliente, il segreto cliente e proprietà aggiuntive.
- Dopo aver convalidato il codice di autorizzazione, il server risponde con un token e, facoltativamente, con un token di aggiornamento. Questo token serve per le richieste autorizzate dall’utente.
- Tulip può ora eseguire richieste per conto degli utenti, utilizzando il token fornito per l’autorizzazione.
Consulta i diagrammi riportati di seguito per comprendere il percorso di esecuzione:
Flusso delle credenziali del client
Il flusso delle credenziali client viene utilizzato principalmente per consentire l’interazione tra due sistemi aziendali. Questo flusso viene configurato una sola volta, quindi condiviso da tutti gli utenti.
- L'utente avvia il flusso facendo clic sul pulsante "Test " prima di salvare un connettore.
- Tulip comunica con il server di autorizzazione del proprio provider OAuth, condividendo parametri specifici quali l’identità del client, gli ambiti (a cosa si sta tentando di accedere) e altri dettagli rilevanti.
- Il server di autorizzazione restituisce un token di accesso, a condizione che l’ID cliente e il segreto cliente siano corretti. Facoltativamente, può essere restituito anche un token di aggiornamento. Questo token serve per le richieste autorizzate dall’utente.
- Tulip può ora eseguire richieste per conto degli utenti, utilizzando il token fornito per l’autorizzazione.
Configurazione di OAuth
The Authorize and Token endpoints must be accessible to the cloud for Tulip to execute authentication for connectors.
URL del codice di autorizzazione
Si tratta dell’URL a cui Tulip si collega nella fase 2 del flusso del codice di autenticazione. È riportato nella documentazione API del proprio provider OAuth e in genere termina con /auth o /authorize.
Nota: questo campo non è presente per le credenziali client.
URL del token di accesso
Dopo la risposta del server di autorizzazione, viene inviata una richiesta all’URL del token di accesso per ottenere un token per l’autenticazione. Generalmente termina con /token.
ID cliente e segreto cliente
Generato dall’interfaccia utente del proprio provider OAuth, l’ID client viene trasmesso con la richiesta iniziale di un codice di autorizzazione. L’ID client e il segreto client accompagnano tutte le richieste di token.
Tempo di scadenza predefinito (in secondi)
Questo campo specifica il tempo predefinito (in secondi) dopo il quale i token verranno aggiornati se non viene esplicitamente fornito un tempo di scadenza o definito tramite un altro meccanismo al di fuori del campo expires_in.
Destinatari e ambito
Il pubblico specifica le risorse specifiche a cui l’utente desidera accedere, mentre l’ambito definisce le azioni desiderate su tali risorse. Entrambi vengono trasmessi durante la richiesta del codice di autorizzazione nella fase 2.
Opzioni aggiuntive
- Invia i dati della richiesta del token in formato JSON: modifica il tipo di codifica della richiesta inviata all’URL del token. Abilitare se necessario per integrazioni specifiche.
- Invia intestazione di autenticazione per la richiesta di aggiornamento: aggiunge un'intestazione aggiuntiva alle richieste di aggiornamento quando è abilitata.
- Ignora richiesta di consenso dell’utente: controlla l’attributo prompt della richiesta del codice di autenticazione. Se disabilitato, imposta il valore su
“consenso”, mentre se abilitato lo imposta su“accesso”, lasciando che sia il provider OAuth a decidere quale schermata di accesso visualizzare.
For some integrations, exclude or set the prompt attribute to none. Reach out to support@tulip.co for further functionality.
Dettagli tecnici
Di seguito sono riportati i dettagli su ciò che Tulip supporta e su come OAuth è integrato per l’autenticazione del connettore.
The Client Credentials flow differs some from the authorization code flow. Steps 1 and 2 are not relevant for the Client Credential flow.
Flusso del codice di autorizzazione di Tulip
The Authorize and Token endpoints must be accessible to the cloud for Tulip to execute authentication for connectors
Tulip avvia il processo di autenticazione quando si testa un connettore o si esegue una funzione del connettore all’interno di un’applicazione.
1. Reindirizzamento al server di autorizzazione
L'applicazione Tulip reindirizza l'utente al server di autorizzazione (AS) insieme a parametri specifici, tra cui response_type (impostato su "code" per il flusso del codice di autorizzazione), client_id (assegnato nell’interfaccia utente del connettore), redirect_uri (predefinito da Tulip), scope e audience (impostati nell’interfaccia utente) e state (una stringa casuale per proteggersi dagli attacchi Cross-Site Request Forgery).
Esempio: GET /authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&audience=AUDIENCE&state=STATE
2. L’utente concede il consenso
Il server di autorizzazione autentica l’utente e gli presenta una schermata di consenso. L’utente può esaminare le autorizzazioni richieste e decidere se concedere o negare l’accesso all’applicazione di terze parti.
:::(Avviso) (Nota)
All’interno della configurazione di un determinato connector, il controllo “Skip user consent prompt” consente di gestire l’attributo prompt nella richiesta di autorizzazione. Se questo controllo è disabilitato, verrà utilizzato il valore consent; se abilitato, verrà utilizzato login.
Se sono necessari ulteriori valori per l’attributo prompt, contatta support@tulip.co e provvederemo ad abilitare ulteriori opzioni per questa proprietà.
:::
3. Codice di autorizzazione
Se l’utente concede il consenso, il server di autorizzazione genera un codice di autorizzazione e reindirizza l’utente a Tulip insieme al codice di autorizzazione. Viene incluso anche il parametro "state", che consente al client di verificare l’integrità della risposta. Questo parametro "state" deve corrispondere al parametro "state" passato al Passo 1.
Esempio di reindirizzamento all’URI di reindirizzamento del client:
REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE
4. Richiesta del token
Il client ora dispone del codice di autorizzazione e lo utilizza per effettuare una richiesta sicura da server a server all’endpoint del token del server di autorizzazione. Il client include il grant_type (impostato su "authorization_code"), il client_id, il client_secret (un segreto noto solo al client e al server di autorizzazione), il redirect_uri e il codice di autorizzazione.
Esempio di richiesta di token:
grant\_type=authorization\_code&code=AUTHORIZATION\_CODE&redirect\_uri=REDIRECT\_URI&client\_id=CLIENT\_ID&client\_secret=CLIENT\_SECRET```
### 5. Risposta con il token di accesso:
Se il codice di autorizzazione è valido, il server di autorizzazione risponde con un token di accesso e, facoltativamente, un token di aggiornamento. Il token di accesso viene utilizzato dal client per autenticarsi quando effettua richieste all’API protetta per conto dell’utente.
**Esempio di risposta con token:**
`{ "access_token": "ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN", "scope": "SCOPE"}`
:::(Warning) (Services Not Using `expires_in`)
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.
:::
### 6. Accesso al server delle risorse
Tulip può ora utilizzare il token di accesso ottenuto per effettuare richieste autorizzate al server delle risorse (API) per conto dell’utente. Il token di accesso è solitamente incluso nell’intestazione Authorization della richiesta HTTP.
**Esempio di richiesta API:**`GET /api/resource Authorization: Bearer ACCESS_TOKEN`
## Gestione della scadenza dei token tramite token di aggiornamento
I server di autorizzazione in genere impostano date di scadenza per i token al fine di regolare l’accesso, con finestre di scadenza variabili a seconda del sistema interfacciato. Tuttavia, i token di breve durata rappresentano una sfida, poiché l’autenticazione costante dell’utente compromette l’esperienza utente nelle applicazioni Tulip.
Per risolvere questo problema, OAuth supporta i token di aggiornamento. Sebbene siano opzionali, sono altamente raccomandati poiché ottimizzano l’esperienza utente consentendo a Tulip di aggiornare i token in modo trasparente senza richiedere l’intervento manuale degli operatori.
### In che modo Tulip gestisce l’aggiornamento dei token?
Quando Tulip rileva che un token di accesso è scaduto, tenta automaticamente di utilizzare il token di aggiornamento associato per ottenere un nuovo token. L’obiettivo principale è ridurre al minimo la necessità di una nuova autenticazione da parte dell’utente. I passaggi seguenti illustrano la logica eseguita da Tulip:
**1. Rilevamento della scadenza:** - Tulip identifica un token scaduto in base al suo attributo `` `expires_in` `` ricevuto nella [fase 5](/r230/docs/oauth20-configuration-and-technical-details#5-access-token-response) del flusso di autenticazione.
:::(Warning) (Services Not Using `expires_in`)
If the token's expiration time is not provided via the `expires_in` key, the "Default Expiration Time (seconds)" field in the authentication configuration will be used to automate token renewal.
:::
**2. Tentativo di flusso dei token:** - Tulip avvia il flusso dei token utilizzando il tipo di concessione `` `refresh_token` ``, sostituendo il tipo di concessione utilizzato nel flusso di autenticazione iniziale.
**3. Convalida del token:** - Se viene ottenuto un nuovo token, Tulip lo memorizza e procede all’esecuzione dell’ connector function richiesto dall’utente. - In caso di esito positivo, i dati vengono forniti al runtime dell’app Tulip. - Se il nuovo token fallisce a causa di un errore OAuth, Tulip riprova il processo fino a 5 volte, tornando ogni volta al passaggio 1. - Se il nuovo token fallisce a causa di qualsiasi altro errore, viene visualizzato un messaggio di errore nel runtime del lettore.
**4. Gestione dell’assenza del token:** - Se non viene fornito un nuovo token, Tulip richiede all’utente nel lettore di effettuare l’autenticazione, avviando l’intero processo di autenticazione. - Al termine, viene eseguita la richiesta connector function e vengono restituiti i dati.
Grazie all’implementazione dei token di aggiornamento, Tulip garantisce un’esperienza utente più fluida gestendo in modo intelligente la scadenza e il rinnovo dei token, riducendo al minimo le interruzioni nel flusso di lavoro.
---
Hai trovato quello che cercavi?
Puoi anche visitare [community.tulip.co](https://community.tulip.co/?utm_source=intercom&utm_medium=article-link&utm_campaign=all) per pubblicare la tua domanda o vedere se altri hanno avuto un problema simile!