Prezentare generală a modurilor de autentificare în Spotnana

Creat de Ashish Chaudhary, Modificat la Du, 5 Oct la 10:49 AM de Ashish Chaudhary

Fluxuri de autentificare Spotnana – Prezentare generală

CUPRINS

Fluxuri de autentificare Spotnana – Prezentare generală
- Componente principale
- Metode de autentificare disponibile

Spotnana pune la dispoziție mai multe metode de autentificare, astfel încât partenerii să poată integra în siguranță platforma noastră. Acest ghid oferă o imagine de ansamblu asupra metodelor de autentificare acceptate de Spotnana, cu explicații detaliate despre modul în care funcționează fiecare flux. Veți regăsi aici descrierea modului în care Spotnana autentifică și autorizează utilizatorii pentru accesul la resursele protejate la nivel de organizație (adică resursele companiei utilizatorului pe platforma Spotnana).

Componente principale

Înainte de a începe, consultați această listă pentru a înțelege termenii esențiali folosiți în acest ghid.

Interfața Spotnana(Interfața cu utilizatorul Spotnana) Se referă la aplicația web Spotnana (instrumentul de rezervare online) sau aplicația mobilă Spotnana. În special, este vorba despre pagina de autentificare, care declanșează fluxul de autentificare atunci când utilizatorul se conectează sau își creează un cont nou.
Serverul Spotnana Reprezintă serverul de backend Spotnana folosit pentru autentificare (de exemplu, pentru autorizarea accesului unui utilizator la o resursă și pentru stocarea și procesarea în siguranță a datelor acestuia).
Interfața partenerului (Interfața cu utilizatorul a partenerului) Interfața (aplicația de frontend) folosită de parteneri pentru a accesa platforma Spotnana. De exemplu, în cazul autentificării prin iFrame, platforma Spotnana este integrată în interfața partenerului, iar utilizatorii accesează Spotnana prin această interfață.
Serverul partenerului Reprezintă unul sau mai multe servere de backend folosite de partenerii noștri pentru integrarea cu Spotnana.
Spotnana IdP (Furnizor de identitate Spotnana) Este serviciul intern Spotnana pentru gestionarea identității și autorizarea utilizatorilor.
IdP al partenerului Furnizori de identitate externi (IdP) utilizați de parteneri. Exemple frecvente sunt Google și Azure.
OBT Instrumentul online de rezervări (OBT) al Spotnana, disponibil la https://app.spotnana.com/
Token de subiect În autentificarea prin iFrame (sau bazată pe schimb de token), tokenul de subiect reprezintă identitatea utilizatorului. Acest token este folosit pentru a prelua informațiile sale și pentru a-i autoriza accesul la platforma Spotnana.
Token de acces O acreditare (OAuth) utilizată de o aplicație parteneră pentru a accesa resurse protejate în numele unui utilizator. Acesta este un cod temporar de autorizare, care permite aplicațiilor să facă solicitări API fără a expune datele de autentificare ale utilizatorului.
Token de reîmprospătare O acreditare cu valabilitate extinsă, folosită pentru a obține noi tokenuri de acces fără ca utilizatorul să fie nevoit să se autentifice din nou. De obicei, este emis împreună cu tokenul de acces la prima autentificare.
Acreditări client Datele furnizate utilizatorilor care se conectează direct la API-urile Spotnana (de exemplu, un clientId și clientSecret).
PID (Identificator personal) Un identificator unic creat pentru utilizator. PID-ul este folosit pentru a prelua informațiile utilizatorului din serverul Spotnana.
orgId Un identificator unic atribuit de Spotnana organizației din care face parte utilizatorul.
tmcId Un identificator unic atribuit de Spotnana pentru o companie de management al călătoriilor (TMC).

Metode de autentificare disponibile

Iată care sunt metodele de autentificare pe care Spotnana le acceptă:

Autentificare cu parolă
- Utilizator existent
- Utilizator nou
Autentificare prin IdP
Autentificare prin API
Autentificare prin iFrame
Autentificare pe bază de cod de autorizare
Autentificare între sisteme (M2M)

Autentificare cu parolă

La autentificarea cu parolă, interfața Spotnana (adică pagina de logare sau de creare cont din OBT) inițiază și gestionează procesul de autentificare cu serverele backend Spotnana. Acest proces poate urma două fluxuri diferite, în funcție de situație: dacă utilizatorul se conectează cu un cont existent sau dacă își creează un cont nou. Ambele scenarii sunt explicate mai jos, cu ajutorul diagramelor de secvență.

Utilizator existent

Diagrama de secvență și pașii de mai jos arată cum interacționează interfața Spotnana cu serviciile backend pentru autentificarea unui utilizator deja existent.

Fig: Diagramă de secvență care explică autentificarea cu parolă pentru utilizatorii existenți.

Pas	Flux
Un utilizator existent se conectează în OBT sau în aplicația mobilă Spotnana folosind adresa de email.
1	Interfața Spotnana trimite o solicitare API către serverul Spotnana pentru a obține informațiile de configurare a autentificării pentru utilizator. Solicitarea conține datele de autentificare ale utilizatorului ca parametri. Răspunsul conține valorile `tmcId`, `orgId`, precum și `authProviderType`.
2	Interfața Spotnana trimite o solicitare API către Spotnana IdP folosind `clientId`, emailul și parola. Spotnana IdP generează un token bearer nou și îl returnează interfeței Spotnana. Prin acest pas, utilizatorul este autentificat.
3	După autentificarea din pasul 2, toate solicitările API ulterioare trebuie să includă tokenul bearer, `orgId`, precum și `tmcId` în antetul solicitării. Tokenul bearer este verificat la fiecare solicitare API, iar răspunsul este trimis către interfața Spotnana.

Utilizator nou

Diagrama de secvență și pașii de mai jos arată cum interacționează interfața Spotnana cu serviciile backend pentru autentificarea unui utilizator nou (sau a unui utilizator existent care dorește să își reseteze parola).

Fig: Diagramă de secvență care explică autentificarea cu parolă pentru utilizatorii noi.

Pas	Flux
Un utilizator nou introduce adresa de email pe pagina de logare OBT Spotnana și apasă pe Următorul.
1	Interfața Spotnana trimite o solicitare API către serverul Spotnana pentru a obține informațiile de configurare a autentificării pentru utilizator. Solicitarea conține datele de autentificare ale utilizatorului ca parametri. Răspunsul conține valorile `tmcId`, `orgId`, precum și `authProviderType`.
1 a	Utilizatorul introduce o parolă nouă și apasă pe Următorul.
2	Interfața Spotnana trimite o solicitare API către Spotnana IdP pentru a înregistra utilizatorul, împreună cu `clientId`, emailul și noua parolă. După înregistrare, utilizatorul primește un cod unic (OTP) pe email.
3	Utilizatorul introduce OTP-ul în interfața Spotnana și apasă pe Verifică. Interfața Spotnana trimite o solicitare către Spotnana IdP pentru a valida OTP-ul și a genera tokenul bearer pentru autentificare. Tokenul bearer este generat și returnat către interfața Spotnana. Acest lucru confirmă autentificarea cu succes a utilizatorului și accesul la platforma Spotnana folosind tokenul bearer.
4	După autentificarea din pasul 3, toate solicitările API ulterioare trebuie să includă tokenul bearer, `orgId`, precum și `tmcId` în antetul solicitării. Tokenul bearer este verificat la fiecare solicitare API, iar răspunsul este trimis către interfața Spotnana.

Autentificare prin IdP

Spotnana permite autentificarea prin IdP-uri precum Google, Azure sau IdP-uri personalizate folosind OpenID Connect sau SAML. Diagrama de secvență și pașii de mai jos prezintă fluxul de autentificare bazat pe IdP.

Fig: Diagramă de secvență care explică fluxul de autentificare prin IdP.

Pas	Flux
Un utilizator se conectează în OBT sau în aplicația mobilă Spotnana folosind adresa de email.
1	Interfața Spotnana trimite o solicitare API către serverul Spotnana pentru a obține informațiile de configurare a autentificării pentru utilizator. Solicitarea conține datele de autentificare ale utilizatorului ca parametri. Răspunsul conține valorile `tmcId`, `orgId`, precum și `authProviderType`.
2	Interfața Spotnana redirecționează solicitarea către Spotnana IdP.
3	Spotnana IdP redirecționează solicitarea către IdP-ul partenerului. Astfel începe autentificarea prin IdP pentru utilizator. Notă: La fiecare redirecționare, se returnează codul de stare 302 pentru a indica faptul că solicitarea a fost redirecționată către o altă adresă URL.
4	Se stabilește o conexiune între Spotnana IdP și IdP-ul partenerului, pentru a verifica dacă utilizatorul este autentificat de către IdP-ul partenerului. Notă: În timpul acestei conexiuni, Spotnana IdP transmite `clientId` și `clientSecret` sub formă de date URL-encoded, printr-un apel API către IdP-ul partenerului. Dacă serverele IdP nu pot procesa acest format, serverul Spotnana poate acționa ca intermediar și transforma datele într-un format acceptat de IdP-ul partenerului.
5	IdP-ul partenerului autentifică cu succes utilizatorul. Notă: După acest pas, profilul utilizatorului trebuie să fie verificat și prin tokenul bearer.
5 a	După autentificarea reușită, răspunsul de la IdP-ul partenerului este transmis către Spotnana IdP.
5 b	Spotnana IdP generează un cod unic pentru profilul utilizatorului și îl trimite către interfața Spotnana.
6	Interfața Spotnana trimite o solicitare API către Spotnana IdP folosind `clientID` și codul primit la pasul 5(b). Spotnana IdP generează un token bearer nou și îl transmite interfeței Spotnana. Notă: Generarea cu succes a tokenului bearer înseamnă că utilizatorul a fost autentificat și are acces la Spotnana.
7	După autentificarea din pasul 6, toate solicitările API ulterioare trebuie să includă tokenul bearer, `orgId`, precum și `tmcId` în antetul solicitării. Tokenul bearer este verificat la fiecare solicitare API, iar răspunsul este trimis către interfața Spotnana.

Autentificare prin API

Partenerii care folosesc API-urile Spotnana pentru conectare pot utiliza endpoint-ul nostru de autentificare pentru a genera un token bearer pentru utilizatorii lor. Diagrama de mai jos ilustrează fluxul de autentificare pentru orice partener care folosește această metodă.

Fig: Diagramă de secvență care explică autentificarea prin API.

Pas Flux

Pas	Flux
1	Utilizatorul API face un apel POST către endpoint-ul `get-auth-token(clientId,clientSecret)` din serverul Spotnana pentru a genera și primi un token bearer temporar. Iată un exemplu de solicitare cUrl pe care o puteți folosi pentru endpoint-ul `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>" }' Notă: Înlocuiți valorile `clientId` și `clientSecret` cu datele de autentificare primite de la Spotnana.
2	Serverul Spotnana apelează metoda `getToken(clientId,clientSecret)` din Spotnana IdP, care generează un `bearerToken` și îl returnează serverului Spotnana. Serverul Spotnana trimite acest token bearer ca răspuns JSON către utilizatorul API.

Utilizatorul API face un apel POST către endpoint-ul get-auth-token(clientId,clientSecret) din serverul Spotnana pentru a genera și primi un token bearer temporar.

Iată un exemplu de solicitare cUrl pe care o puteți folosi pentru endpoint-ul 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>"
}'

Notă: Înlocuiți valorile clientId și clientSecret cu datele de autentificare primite de la Spotnana.

Serverul Spotnana apelează metoda getToken(clientId,clientSecret) din Spotnana IdP, care generează un bearerToken și îl returnează serverului Spotnana.
Serverul Spotnana trimite acest token bearer ca răspuns JSON către utilizatorul API.

După ce utilizatorul API a primit tokenul bearer, toate cererile ulterioare către API-urile Spotnana (de exemplu, Trip APIs) trebuie să includă tokenul bearer în antet pentru autorizare.

Notă: Endpoint-ul get-auth-token(clientId, clientSecret) permite maximum 100 de apeluri API la fiecare 5 minute.

Autentificare prin iFrame

O soluție iFrame sau integrată presupune ca partenerii să includă interfața Spotnana în propria lor interfață, astfel încât utilizatorii accesează Spotnana prin UI-ul partenerului. În acest caz, autentificarea se realizează prin schimb de tokenuri între sistemul partenerului și Spotnana.

Notă: În cazul autentificării prin iFrame, utilizatorul care se conectează va fi denumit apelant. Acest termen este folosit pentru scenariile în care un utilizator API/Machine se conectează și solicită un token de acces pentru alt utilizator. Acest utilizator API/Machine poate folosi datele de administrator TMC pentru a se conecta direct la serverul Spotnana. De aceea, vom folosi termenul apelant ca denumire generală, care poate însemna fie un utilizator care se conectează la propriul profil, fie un utilizator API/Machine care solicită un token de acces pentru altcineva.

Diagrama de secvență de mai jos arată cum se realizează autentificarea prin schimb de tokenuri între serverele Spotnana și ale partenerului.

Fig: Diagramă de secvență care explică autentificarea prin iFrame cu schimb de tokenuri.

Pas	Flux
Un apelant se conectează folosind interfața partenerului.
1	Interfața partenerului afișează interfața Spotnana prin iFrame.
2	Interfața Spotnana trimite o solicitare către interfața partenerului, printr-un mesaj post, pentru a obține tokenurile. Solicitarea are parametrul `type=TOKEN_EXCHANGE_REQUEST`.
3	Interfața partenerului trimite o solicitare API către serverul partenerului pentru a obține tokenul OAuth, continuând pașii următori ai fluxului de autentificare.
3 a	Serverul partenerului apelează serverul Spotnana folosind datele de autentificare ale utilizatorului și tokenul de subiect ca parametri. Serverul Spotnana verifică dacă solicitarea provine de la un utilizator API/Machine.
3 b	Serverul Spotnana apelează serverul partenerului pentru a obține adresa de email a subiectului (apelantului). Emailul este preluat și returnat către serverul Spotnana, fiind folosit pentru identificarea utilizatorului.
3 c	Răspunsul la solicitarea API din pasul 1 este transmis de serverul Spotnana către serverul partenerului și conține tokenul de acces și tokenul de reîmprospătare. Aceste date sunt apoi transmise către interfața partenerului.
4	Interfața partenerului transmite tokenul către interfața Spotnana printr-un mesaj post cu `type=TOKEN_EXCHANGE_RESPONSE.`
5	Interfața Spotnana trimite o solicitare API către serverul Spotnana pentru a genera și primi un nou token bearer. Serverul Spotnana generează tokenul bearer și îl returnează interfeței Spotnana. Notă: Generarea cu succes a tokenului bearer înseamnă că utilizatorul a fost autentificat și are acces la Spotnana.
6	După autentificarea din pasul 3, toate solicitările API ulterioare trebuie să includă tokenul bearer, `orgId`, precum și `tmcId` în antetul solicitării. Tokenul bearer este verificat la fiecare solicitare API, iar răspunsul este trimis către interfața Spotnana.

Autentificare pe bază de cod de autorizare

Diagrama de mai jos arată cum se realizează fluxul de autentificare folosind un cod de autorizare.

Fig: Diagramă de secvență care explică autentificarea pe bază de cod de autorizare.

Pas	Flux
1	Interfața partenerului apelează serverul partenerului pentru a obține codul de autorizare pentru apelantul care se conectează. Codul este preluat și transmis către interfața partenerului.
2	Interfața partenerului trimite o solicitare către interfața Spotnana folosind o adresă URL personalizată de redirecționare care conține `tmcId` și `authCode` ca parametri.
3	Interfața Spotnana face un apel POST către serverul Spotnana folosind endpoint-ul `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	Serverul Spotnana trimite o solicitare către serverul partenerului pentru a obține `pid` folosind codul de autorizare. PID-ul utilizatorului `pid` este preluat și transmis serverului Spotnana.
3 b	Tokenul de acces și tokenul de reîmprospătare sunt generate de serverul Spotnana și trimise către interfața Spotnana.
4	Interfața Spotnana trimite o solicitare către serverul Spotnana folosind tokenul de acces și tokenul de reîmprospătare pentru a genera și primi tokenul bearer de acces. Un token bearer este generat și transmis către interfața Spotnana. Notă: Generarea cu succes a tokenului bearer înseamnă că utilizatorul a fost autentificat și are acces la Spotnana.
5	După autentificarea din pasul 4, toate solicitările API ulterioare trebuie să includă tokenul bearer, `orgId`, precum și `tmcId` în antetul solicitării. Tokenul bearer este verificat la fiecare solicitare API, iar răspunsul este trimis către interfața Spotnana.

Notă: Acest flux de autentificare nu poate fi folosit în situațiile în care un administrator TMC permite mai multor utilizatori să folosească aceeași adresă de email la autentificare.

Autentificare între sisteme (M2M)

Metoda de autentificare M2M este potrivită atunci când aplicația client accesează o adresă URL de callback externă pentru a genera accessToken pentru utilizator. Diagrama de mai jos ilustrează fluxul de autentificare M2M.

Fig: Diagramă de secvență care explică fluxul de autentificare M2M.

Pas	Flux
Cheile publice pentru toate aplicațiile implicate în autentificare sunt sincronizate între serverul Spotnana și Spotnana IdP. Acestea vor fi folosite ulterior pentru verificarea tokenului de acces pe parcursul autentificării.
1	Serverul partenerului trimite o solicitare API către `/oauth2/token(clientId,clientSecret)` în Spotnana IdP pentru a genera un token bearer. Noul token bearer este returnat serverului partenerului.
2	Serverul partenerului trimite o solicitare API către o adresă URL de callback externă pentru a genera un token de acces pentru utilizator. Acest token de acces este creat și transmis către serverul Spotnana.
3	Serverul Spotnana validează semnătura tokenului de acces folosind cheile publice sincronizate anterior. De asemenea, verifică `claim_id` care confirmă identitatea partenerului. Tokenul de acces este apoi transmis serverului partenerului pentru autentificarea utilizatorului.