Panoramica dei metodi di autenticazione Spotnana

Creato da Ashish Chaudhary, Modificato il Dom, 5 Ott alle 4:40 AM di Ashish Chaudhary

Panoramica dei flussi di autenticazione Spotnana

INDICE DEI CONTENUTI

Panoramica dei flussi di autenticazione Spotnana
- Componenti principali
- Metodi di autenticazione supportati

Spotnana mette a disposizione diversi metodi di autenticazione che consentono ai partner di integrare la propria piattaforma in modo sicuro. In questa documentazione troverete una panoramica delle modalità di autenticazione attualmente disponibili su Spotnana, insieme a una spiegazione dettagliata del funzionamento di ciascun flusso. I flussi descritti illustrano come Spotnana gestisce l’autenticazione e l’autorizzazione degli utenti per l’accesso alle risorse protette a livello organizzativo (ossia, le risorse della società dell’utente sulla piattaforma Spotnana).

Componenti principali

Prima di iniziare, consultate questo elenco per conoscere le definizioni dei componenti essenziali menzionati nella documentazione.

Interfaccia Spotnana(Interfaccia utente Spotnana) Si riferisce all’applicazione web di Spotnana (ossia, lo strumento di prenotazione online) o all’app mobile Spotnana. In particolare, si intende la pagina di accesso, che avvia la procedura di autenticazione quando l’utente effettua il login o crea un nuovo account.
Server Spotnana Rappresenta il server backend di Spotnana utilizzato per le procedure di autenticazione (ad esempio, per autorizzare l’accesso alle risorse e per conservare e gestire in sicurezza le informazioni dell’utente).
Interfaccia partner (Interfaccia utente del partner) L’interfaccia utente (ossia, l’applicazione frontend) utilizzata dai partner per accedere alla piattaforma Spotnana. Ad esempio, nell’autenticazione tramite iFrame, la piattaforma Spotnana viene integrata all’interno dell’interfaccia del partner e gli utenti accedono a Spotnana attraverso questa interfaccia.
Server partner Indica uno o più server backend utilizzati dai nostri partner per integrare i propri sistemi con Spotnana.
Spotnana IdP (Identity Provider di Spotnana) Si tratta del servizio interno di Spotnana dedicato alla gestione delle identità e all’autorizzazione degli utenti.
IdP partner Fornitori di identità di terze parti (IdP) utilizzati dai partner. Tra i più comuni troviamo Google e Azure.
OBT Lo strumento di prenotazione online (Online Booking Tool, OBT) di Spotnana, accessibile all’indirizzo https://app.spotnana.com/
Token soggetto Nell’autenticazione tramite iFrame (o scambio di token), il token soggetto rappresenta l’identità dell’utente. Questo token viene utilizzato per recuperare le informazioni dell’utente e autorizzarne l’accesso alla piattaforma Spotnana.
Token di accesso Una credenziale (OAuth) utilizzata da un’applicazione partner per accedere a risorse protette per conto dell’utente. Si tratta di una chiave di autorizzazione temporanea che consente alle applicazioni di effettuare richieste API senza esporre le credenziali dell’utente.
Token di rinnovo Una credenziale a lunga durata che permette di ottenere nuovi token di accesso senza che l’utente debba autenticarsi nuovamente. Di solito viene rilasciata insieme al token di accesso durante la prima sessione di accesso.
Credenziali client Le informazioni fornite agli utenti che si connettono direttamente alle API di Spotnana (ad esempio, uno specifico clientId e clientSecret).
PID (Identificativo personale) Un identificativo personale creato per l’utente. Il PID consente di recuperare le informazioni dell’utente dal server Spotnana.
orgId Identificativo univoco assegnato da Spotnana all’organizzazione dell’utente.
tmcId Identificativo univoco assegnato da Spotnana a una TMC (Travel Management Company).

Metodi di autenticazione supportati

Di seguito sono elencati i diversi metodi di autenticazione disponibili su Spotnana:

Autenticazione tramite password
- Utente esistente
- Nuovo utente
Autenticazione tramite IdP
Autenticazione tramite API
Autenticazione tramite iFrame
Autenticazione tramite codice di autorizzazione
Autenticazione machine-to-machine (M2M)

Autenticazione tramite password

Quando si utilizza l’autenticazione tramite password, l’interfaccia Spotnana (ossia, la pagina di accesso o registrazione dell’OBT) avvia e gestisce il processo di autenticazione con i server backend di Spotnana. Questo approccio può seguire due flussi distinti a seconda che l’utente acceda con un profilo già esistente oppure si registri per crearne uno nuovo. Entrambi i flussi vengono illustrati di seguito tramite diagrammi di sequenza.

Utente esistente

Il diagramma di sequenza e i passaggi riportati spiegano come l’interfaccia Spotnana interagisce con i servizi backend per autenticare un utente già registrato.

Fig: Diagramma di sequenza che illustra l’autenticazione tramite password per gli utenti già esistenti.

Fase	Flusso
Un utente già registrato effettua l’accesso tramite OBT o tramite l’app mobile Spotnana utilizzando la propria email.
1	L’interfaccia Spotnana invia una richiesta API al server Spotnana per recuperare le informazioni di configurazione dell’autenticazione dell’utente. La richiesta include le credenziali di accesso dell’utente come parametri. La risposta contiene il `tmcId`, `orgId`e il tipo di `authProviderType`.
2	L’interfaccia Spotnana invia una richiesta API allo Spotnana IdP utilizzando il `clientId`, l’email e la password. Lo Spotnana IdP genera un nuovo bearer token e lo restituisce all’interfaccia Spotnana. Con questo passaggio l’utente viene autenticato.
3	Dopo l’autenticazione dell’utente al punto 2, tutte le successive richieste API devono includere il bearer token, l’ `orgId`e il `tmcId` nell’intestazione della richiesta. Il bearer token viene verificato in tutte le richieste API in ingresso e la risposta viene inviata all’interfaccia Spotnana.

Nuovo utente

Il diagramma di sequenza e i passaggi seguenti spiegano come l’interfaccia Spotnana interagisce con i servizi backend per autenticare un nuovo utente (o un utente esistente che desidera reimpostare la password).

Fig: Diagramma di sequenza che illustra l’autenticazione tramite password per i nuovi utenti.

Fase	Flusso
Un nuovo utente inserisce la propria email nella pagina di accesso dell’OBT Spotnana e seleziona Avanti.
1	L’interfaccia Spotnana invia una richiesta API al server Spotnana per recuperare le informazioni di configurazione dell’autenticazione dell’utente. La richiesta include le credenziali di accesso dell’utente come parametri. La risposta contiene il `tmcId`, `orgId`e il tipo di `authProviderType`.
1 a	L’utente inserisce una nuova password e seleziona Avanti.
2	L’interfaccia Spotnana invia una richiesta API allo Spotnana IdP per registrare l’utente insieme al `clientId`, all’email e alla nuova password. Dopo la registrazione, viene inviato all’utente un codice OTP (One-Time Password) tramite email.
3	L’utente inserisce l’OTP nell’interfaccia Spotnana e seleziona Verifica. L’interfaccia Spotnana invia una richiesta allo Spotnana IdP per verificare l’OTP e generare un bearer token per l’accesso. Il bearer token viene generato e restituito all’interfaccia Spotnana. Questo conferma che l’utente è stato autenticato con successo e può accedere alla piattaforma Spotnana tramite il bearer token.
4	Dopo l’autenticazione dell’utente al punto 3, tutte le successive richieste API devono includere il bearer token, l’ `orgId`e il `tmcId` nell’intestazione della richiesta. Il bearer token viene verificato in tutte le richieste API in ingresso e la risposta viene inviata all’interfaccia Spotnana.

Autenticazione tramite IdP

Spotnana consente l’autenticazione tramite IdP come Google, Azure e IdP personalizzati utilizzando OpenID Connect o SAML. Il diagramma di sequenza e i passaggi seguenti illustrano il flusso di autenticazione tramite IdP.

Fig: Diagramma di sequenza che illustra il flusso di autenticazione tramite IdP.

Fase	Flusso
Un utente effettua l’accesso tramite OBT o tramite l’app mobile Spotnana utilizzando la propria email.
1	L’interfaccia Spotnana invia una richiesta API al server Spotnana per recuperare le informazioni di configurazione dell’autenticazione dell’utente. La richiesta include le credenziali di accesso dell’utente come parametri. La risposta contiene il `tmcId`, `orgId`e il tipo di `authProviderType`.
2	L’interfaccia Spotnana reindirizza la richiesta allo Spotnana IdP.
3	Lo Spotnana IdP reindirizza la richiesta all’IdP del partner, avviando così la procedura di autenticazione tramite IdP per l’utente. Nota: A ogni reindirizzamento viene restituito un codice di stato 302 per indicare che la richiesta è stata inoltrata a un URL diverso.
4	Viene stabilita una connessione tra Spotnana IdP e l’IdP del partner per garantire che l’utente sia autenticato dal partner. Nota: Durante questa connessione, Spotnana IdP invia il `clientId` e il `clientSecret` come dati codificati in formato URL tramite una chiamata API all’IdP del partner. Se i server IdP non sono in grado di elaborare questo formato, il server Spotnana può fungere da intermediario e convertire i dati in un formato compatibile con l’IdP del partner.
5	L’IdP del partner autentica correttamente l’utente. Nota: Dopo questo passaggio, il profilo utente deve comunque essere verificato tramite il bearer token.
5 a	Dopo l’autenticazione, la risposta dell’IdP del partner viene inviata allo Spotnana IdP.
5 b	Spotnana IdP genera un codice univoco per il profilo utente e lo invia all’interfaccia Spotnana.
6	L’interfaccia Spotnana invia una richiesta API allo Spotnana IdP utilizzando il `clientID` e il codice ricevuto al punto 5(b). Lo Spotnana IdP genera un nuovo bearer token e lo invia all’interfaccia Spotnana. Nota: La creazione del bearer token conferma che l’utente è stato autenticato e può accedere a Spotnana.
7	Dopo l’autenticazione dell’utente al punto 6, tutte le successive richieste API devono includere il bearer token, l’ `orgId`e il `tmcId` nell’intestazione della richiesta. Il bearer token viene verificato in tutte le richieste API in ingresso e la risposta viene inviata all’interfaccia Spotnana.

Autenticazione tramite API

I partner che utilizzano le API di Spotnana per collegarsi alla piattaforma possono utilizzare il nostro endpoint di autenticazione per generare un bearer token per i propri utenti. Il diagramma di sequenza seguente mostra il flusso di autenticazione per i partner che adottano questa modalità.

Fig: Diagramma di sequenza che illustra l’autenticazione tramite API.

Fase Flusso

Fase	Flusso
1	L’utente API esegue una chiamata POST all’endpoint `get-auth-token(clientId,clientSecret)` sul server Spotnana per generare e ricevere un bearer token temporaneo. Ecco un esempio di richiesta cUrl da utilizzare per chiamare l’endpoint `get-auth-token` : curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Nota: Sostituire i valori di `clientId` e `clientSecret` con le credenziali ricevute da Spotnana.
2	Il server Spotnana richiama il metodo `getToken(clientId,clientSecret)` nello Spotnana IdP, che genera un `bearerToken` e lo restituisce al server Spotnana. Il server Spotnana invia il bearer token come risposta JSON all’utente API.

L’utente API esegue una chiamata POST all’endpoint get-auth-token(clientId,clientSecret) sul server Spotnana per generare e ricevere un bearer token temporaneo.

Ecco un esempio di richiesta cUrl da utilizzare per chiamare l’endpoint get-auth-token :

curl -i -X POST \
https://api.spotnana.com/get-auth-token \
-H 'Content-Type: application/json' \
-d '{
  "clientId": "sample-apiuser@tmcorg.com",
  "clientSecret": "<password>"
}'

Nota: Sostituire i valori di clientId e clientSecret con le credenziali ricevute da Spotnana.

Il server Spotnana richiama il metodo getToken(clientId,clientSecret) nello Spotnana IdP, che genera un bearerToken e lo restituisce al server Spotnana.
Il server Spotnana invia il bearer token come risposta JSON all’utente API.

Una volta ricevuto il bearer token, tutte le richieste successive alle API Spotnana (ad esempio, alle API Viaggio]) devono includere il bearer token nell’intestazione per l’autorizzazione.

Nota: L’endpoint get-auth-token(clientId, clientSecret) ha un limite di 100 chiamate API ogni 5 minuti.

Autenticazione tramite iFrame

La soluzione tramite iFrame o integrata prevede che i partner inseriscano l’interfaccia Spotnana all’interno della propria interfaccia, consentendo agli utenti di accedere a Spotnana tramite il portale del partner. In questo scenario, l’autenticazione dell’utente si basa su uno scambio di token tra i sistemi del partner e Spotnana.

Nota: Per l’autenticazione tramite iFrame, l’utente che effettua l’accesso viene chiamato caller. Questo per coprire anche casi specifici in cui un utente API/Machine accede e richiede un token di accesso per un altro utente. In questi casi, l’utente API/Machine può utilizzare le credenziali di amministratore TMC per collegarsi direttamente al server Spotnana. Per questo motivo, il termine caller viene utilizzato in senso generale, sia per l’utente che accede al proprio profilo sia per l’utente API/Machine che richiede un token di accesso per conto di un altro utente.

Il diagramma di sequenza seguente mostra come avviene il flusso di autenticazione tramite scambio di token tra Spotnana e i server del partner.

Fig: Diagramma di sequenza che illustra l’autenticazione tramite iFrame con scambio di token.

Fase	Flusso
Un caller effettua l’accesso utilizzando l’interfaccia partner.
1	L’interfaccia partner visualizza l’interfaccia Spotnana tramite iFrame.
2	L’interfaccia Spotnana invia una richiesta all’interfaccia partner tramite post message per recuperare i token. La richiesta include `type=TOKEN_EXCHANGE_REQUEST`.
3	L’interfaccia partner invia una richiesta API al server partner per ottenere il token OAuth, avviando così i passaggi successivi del flusso di autenticazione.
3 a	Il server partner chiama il server Spotnana utilizzando le credenziali dell’utente e il token soggetto come parametri. Il server Spotnana verifica se la richiesta proviene da un utente API/Machine.
3 b	Il server Spotnana chiama il server partner per recuperare l’email del soggetto (cioè del caller). L’email viene recuperata e restituita al server Spotnana, che la utilizza per identificare l’utente.
3 c	La risposta alla richiesta API del punto 1 viene inviata dal server Spotnana al server partner e contiene l’access token e il refresh token. Questi dati vengono poi inoltrati all’interfaccia partner.
4	L’interfaccia partner invia il token all’interfaccia Spotnana tramite post message con `type=TOKEN_EXCHANGE_RESPONSE.`
5	L’interfaccia Spotnana invia una richiesta API al server Spotnana per generare e ricevere un nuovo bearer token. Il bearer token viene generato dal server Spotnana e restituito all’interfaccia Spotnana. Nota: La creazione del bearer token conferma che l’utente è stato autenticato e può accedere a Spotnana.
6	Dopo l’autenticazione dell’utente al punto 3, tutte le successive richieste API devono includere il bearer token, l’ `orgId`e il `tmcId` nell’intestazione della richiesta. Il bearer token viene verificato in tutte le richieste API in ingresso e la risposta viene inviata all’interfaccia Spotnana.

Autenticazione tramite codice di autorizzazione

Il diagramma di sequenza seguente mostra come avviene il flusso di autenticazione utilizzando un codice di autorizzazione.

Fig: Diagramma di sequenza che illustra l’autenticazione tramite codice di autorizzazione.

Fase	Flusso
1	L’interfaccia partner chiama il server partner per recuperare il codice di autorizzazione per il caller che sta effettuando l’accesso. Il codice viene recuperato e restituito all’interfaccia partner.
2	L’interfaccia partner invia una richiesta all’interfaccia Spotnana tramite un URL di reindirizzamento personalizzato contenente il `tmcId` e l’ `authCode` come parametri.
3	L’interfaccia Spotnana effettua una chiamata POST API al server Spotnana utilizzando l’endpoint `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	Il server Spotnana invia una richiesta al server partner per recuperare il `pid` dell’utente utilizzando il codice di autorizzazione. Il `pid` dell’utente viene recuperato e inviato al server Spotnana.
3 b	Il server Spotnana genera l’access token e il refresh token e li invia all’interfaccia Spotnana.
4	L’interfaccia Spotnana invia una richiesta al server Spotnana utilizzando l’access token e il refresh token per generare e ricevere il bearer token per l’accesso. Il bearer token viene generato e inviato all’interfaccia Spotnana. Nota: La creazione del bearer token conferma che l’utente è stato autenticato e può accedere a Spotnana.
5	Dopo l’autenticazione dell’utente al punto 4, tutte le successive richieste API devono includere il bearer token, l’ `orgId`e il `tmcId` nell’intestazione della richiesta. Il bearer token viene verificato in tutte le richieste API in ingresso e la risposta viene inviata all’interfaccia Spotnana.

Nota: Questo flusso di autenticazione non è utilizzabile nei casi in cui un amministratore TMC consente a più utenti di accedere con la stessa email.

Autenticazione machine-to-machine (M2M)

Il metodo di autenticazione M2M è adatto quando il flusso di autenticazione prevede che l’applicazione client acceda a un URL di callback di terze parti per generare l’ accessToken dell’utente. Il diagramma di sequenza seguente illustra il flusso di autenticazione M2M.

Fig: Diagramma di sequenza che illustra il flusso di autenticazione M2M.

Fase	Flusso
Le chiavi pubbliche di tutte le applicazioni coinvolte nell’autenticazione vengono sincronizzate tra il server Spotnana e lo Spotnana IdP. Queste chiavi verranno poi utilizzate per verificare il token di accesso durante il flusso di autenticazione.
1	Il server partner invia una richiesta API a `/oauth2/token(clientId,clientSecret)` sullo Spotnana IdP per generare un bearer token. Il nuovo bearer token viene restituito al server partner.
2	Il server partner invia una richiesta API a un URL di callback di terze parti per generare un access token per l’utente. Questo access token viene creato e inviato al server Spotnana.
3	Il server Spotnana verifica la firma dell’access token utilizzando le chiavi pubbliche sincronizzate in precedenza. Inoltre, controlla il `claim_id` che serve a verificare l’identità del partner. L’access token viene quindi inviato al server partner per autenticare l’utente.