Pregled načina prijave u Spotnana sustav

Izradio Ashish Chaudhary, Promijenjeno na Sun, 5 Lis na 5:51 PRIJEPODNE od Ashish Chaudhary

This article is not available in Slovak, view it in English

Spotnana načini autentikacije – pregled

SADRŽAJ

Spotnana načini autentikacije – pregled
- Ključne komponente
- Podržane metode autentikacije

Spotnana omogućuje više načina autentikacije kako bi partnerima omogućila sigurnu integraciju s našom platformom. Ova dokumentacija daje pregled različitih metoda autentikacije koje su trenutno dostupne na Spotnani, uz detaljna objašnjenja tijeka svakog procesa. Prikazani načini autentikacije pokazuju kako Spotnana provjerava i odobrava pristup korisnicima na zaštićenim resursima na razini organizacije (odnosno, resursima kojima upravlja tvrtka korisnika na Spotnana platformi).

Ključne komponente

Prije nego što krenete, proučite ovaj popis osnovnih sustavskih pojmova koji se koriste u ovoj dokumentaciji.

Spotnana UI(Korisničko sučelje Spotnana) Odnosi se na Spotnana web aplikaciju (Online Booking Tool) ili mobilnu aplikaciju. Najčešće se misli na stranicu za prijavu, koja pokreće autentikaciju kada se korisnik prijavljuje ili kreira novi račun.
Spotnana poslužitelj Odnosi se na Spotnana pozadinski poslužitelj koji se koristi za autentikaciju (npr. ovjeravanje pristupa korisnika određenom resursu te sigurno pohranjivanje i obradu korisničkih podataka).
Partner UI (Korisničko sučelje partnera) Korisničko sučelje (odnosno frontend aplikacija) koje partneri koriste za pristup Spotnana platformi. Na primjer, kod autentikacije putem iFrame-a, Spotnana platforma je ugrađena u korisničko sučelje partnera i njihovi korisnici pristupaju Spotnani kroz to sučelje.
Partner poslužitelj Odnosi se na jedan ili više pozadinskih poslužitelja koje partneri koriste za integraciju sa Spotnanom.
Spotnana IdP (Spotnana davatelj identiteta) Odnosi se na interni Spotnana servis za upravljanje identitetima i ovlaštenjima korisnika.
Partner IdP Davatelji identiteta trećih strana koje koriste partneri. Najčešći primjeri su Google i Azure.
OBT Spotnana Online Booking Tool (OBT), kojem možete pristupiti na https://app.spotnana.com/
Subject token Kod autentikacije putem iFrame-a (ili razmjene tokena), subject token predstavlja identitet korisnika. Ovaj token koristi se za dohvat korisničkih podataka i odobravanje pristupa Spotnana platformi.
Access token Pristupni token (OAuth) koji partnerska aplikacija koristi za pristup zaštićenim resursima u ime korisnika. To je privremeni ključ koji omogućuje aplikacijama slanje API zahtjeva bez izravnog otkrivanja korisničkih vjerodajnica.
Refresh token Token za osvježavanje pristupa – dugotrajnija vjerodajnica koja omogućuje dobivanje novih pristupnih tokena bez ponovne autentikacije korisnika. Obično se izdaje zajedno s pristupnim tokenom prilikom prve prijave.
Client credentials Podaci koje dobivaju korisnici koji se izravno spajaju na Spotnana API-je (npr. jedinstveni clientId i clientSecret).
PID (Osobni identifikator) Osobni identifikator koji se dodjeljuje korisniku. PID služi za dohvat korisničkih podataka sa Spotnana poslužitelja.
orgId Jedinstveni identifikator koji Spotnana dodjeljuje organizaciji korisnika.
tmcId Jedinstveni identifikator koji Spotnana dodjeljuje TMC-u (Travel Management Company).

Podržane metode autentikacije

Spotnana podržava sljedeće metode autentikacije:

Autentikacija pomoću lozinke
- Postojeći korisnik
- Novi korisnik
Autentikacija putem IdP-a
Autentikacija putem API-ja
Autentikacija putem iFrame-a
Autentikacija putem autorizacijskog koda
Autentikacija između strojeva (M2M)

Autentikacija pomoću lozinke

Pri autentikaciji pomoću lozinke, Spotnana UI (odnosno stranica za prijavu ili registraciju u OBT-u) pokreće i upravlja procesom autentikacije s pozadinskim poslužiteljima Spotnane. Ovisno o tome prijavljuje li se korisnik s postojećim profilom ili kreira novi, postoje dva različita tijeka. Svaki od tih tijekova detaljno je prikazan u nastavku kroz dijagrame i opisane korake.

Postojeći korisnik

Dijagram slijeda i koraci u nastavku prikazuju kako Spotnana UI komunicira s pozadinskim servisima radi autentikacije postojećeg korisnika.

Slika: Dijagram slijeda koji prikazuje autentikaciju pomoću lozinke za postojeće korisnike.

Korak	Tijek
Postojeći korisnik se prijavljuje putem OBT-a ili Spotnana mobilne aplikacije koristeći svoju e-mail adresu.
1	Spotnana UI šalje API zahtjev Spotnana poslužitelju kako bi preuzeo podatke o konfiguraciji autentikacije za korisnika. Zahtjev sadrži korisničke vjerodajnice. Odgovor sadrži korisnikov `tmcId`, `orgId`i `authProviderType`.
2	Spotnana UI šalje API zahtjev Spotnana IdP-u koristeći `clientId`, e-mail i lozinku. Spotnana IdP generira novi bearer token i vraća ga Spotnana UI-ju. Ovim korakom korisnik je autentificiran.
3	Nakon što je korisnik autentificiran u koraku 2, svi daljnji API zahtjevi moraju sadržavati bearer token, `orgId`i `tmcId` u zaglavlju zahtjeva. Bearer token se provjerava u svim dolaznim API zahtjevima, a odgovor se vraća Spotnana UI-ju.

Novi korisnik

Dijagram slijeda i koraci u nastavku prikazuju kako Spotnana UI komunicira s pozadinskim servisima radi autentikacije novog korisnika (ili postojećeg korisnika koji pokušava resetirati lozinku).

Slika: Dijagram slijeda koji prikazuje autentikaciju pomoću lozinke za nove korisnike.

Korak	Tijek
Novi korisnik unosi svoju e-mail adresu na OBT stranici za prijavu i klikne Dalje.
1	Spotnana UI šalje API zahtjev Spotnana poslužitelju kako bi preuzeo podatke o konfiguraciji autentikacije za korisnika. Zahtjev sadrži korisničke vjerodajnice. Odgovor sadrži korisnikov `tmcId`, `orgId`i `authProviderType`.
1 a	Korisnik unosi novu lozinku i klikne Dalje.
2	Spotnana UI šalje API zahtjev Spotnana IdP-u za registraciju korisnika s njegovim `clientId`, e-mail adresom i novom lozinkom. Nakon registracije podataka, korisniku se na e-mail šalje jednokratna lozinka (OTP).
3	Korisnik unosi OTP u Spotnana UI i klikne Potvrdi. Spotnana UI šalje zahtjev Spotnana IdP-u za provjeru OTP-a i generiranje bearer tokena za prijavu. Bearer token se generira i vraća Spotnana UI-ju. Time je korisnik uspješno autentificiran i može pristupiti Spotnana platformi koristeći taj token.
4	Nakon što je korisnik autentificiran u koraku 3, svi daljnji API zahtjevi moraju sadržavati bearer token, `orgId`i `tmcId` u zaglavlju zahtjeva. Bearer token se provjerava u svim dolaznim API zahtjevima, a odgovor se vraća Spotnana UI-ju.

Autentikacija putem IdP-a

Spotnana podržava autentikaciju putem IdP-ova kao što su Google, Azure te prilagođeni IdP-ovi koristeći OpenID Connect, kao i SAML protokole. Dijagram slijeda i koraci u nastavku prikazuju tijek autentikacije putem IdP-a.

Slika: Dijagram slijeda koji prikazuje tijek autentikacije putem IdP-a.

Korak	Tijek
Korisnik se prijavljuje putem OBT-a ili Spotnana mobilne aplikacije koristeći svoju e-mail adresu.
1	Spotnana UI šalje API zahtjev Spotnana poslužitelju kako bi preuzeo podatke o konfiguraciji autentikacije za korisnika. Zahtjev sadrži korisničke vjerodajnice. Odgovor sadrži korisnikov `tmcId`, `orgId`i `authProviderType`.
2	Spotnana UI preusmjerava zahtjev na Spotnana IdP.
3	Spotnana IdP preusmjerava zahtjev na partnerov IdP. Time započinje autentikacija kod partnerovog IdP-a. Napomena: Za svako preusmjeravanje vraća se statusni kod 302, što označava preusmjerenje na drugu adresu.
4	Uspostavlja se veza između Spotnana IdP-a i partnerovog IdP-a kako bi se provjerila autentičnost korisnika kod partnera. Napomena: Tijekom ove veze, Spotnana IdP šalje `clientId` i `clientSecret` kao podatke kodirane u URL-u putem API poziva prema partnerovom IdP-u. Ako IdP poslužitelji ne mogu obraditi taj format, Spotnana poslužitelj može poslužiti kao posrednik i prevesti podatke u odgovarajući format za partnerov IdP.
5	Partnerov IdP uspješno autentificira korisnika. Napomena: Nakon ovog koraka, korisnički profil još uvijek mora proći provjeru bearer tokena.
5 a	Nakon uspješne autentikacije, odgovor partnerovog IdP-a šalje se Spotnana IdP-u.
5 b	Spotnana IdP generira jedinstveni kod za korisnički profil i šalje ga Spotnana UI-ju.
6	Spotnana UI šalje API zahtjev Spotnana IdP-u koristeći `clientID` i kod dobiven u koraku 5(b). Spotnana IdP generira novi bearer token i šalje ga Spotnana UI-ju. Napomena: Uspješno kreiran bearer token znači da je korisnik autentificiran i može pristupiti Spotnani.
7	Nakon što je korisnik autentificiran u koraku 6, svi daljnji API zahtjevi moraju sadržavati bearer token, `orgId`i `tmcId` u zaglavlju zahtjeva. Bearer token se provjerava u svim dolaznim API zahtjevima, a odgovor se vraća Spotnana UI-ju.

Autentikacija putem API-ja

Partneri koji koriste Spotnana API-je za povezivanje s platformom mogu koristiti našu autentikacijsku točku za generiranje bearer tokena za svoje korisnike. Sljedeći dijagram prikazuje tijek autentikacije za partnere koji koriste ovaj način.

Slika: Dijagram slijeda koji prikazuje autentikaciju putem API-ja.

Korak Tijek

Korak	Tijek
1	Korisnik API-ja šalje POST zahtjev prema `get-auth-token(clientId,clientSecret)` API točki na Spotnana poslužitelju kako bi generirao i preuzeo privremeni bearer token. Primjer cUrl zahtjeva koji možete koristiti za pozivanje `get-auth-token` točke: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Napomena: Zamijenite vrijednosti `clientId` i `clientSecret` s podacima koje ste dobili od Spotnane.
2	Spotnana poslužitelj poziva `getToken(clientId,clientSecret)` metodu na Spotnana IdP-u, koji generira privremeni `bearerToken` i vraća ga Spotnana poslužitelju. Spotnana poslužitelj šalje taj bearer token kao JSON odgovor korisniku API-ja.

Korisnik API-ja šalje POST zahtjev prema get-auth-token(clientId,clientSecret) API točki na Spotnana poslužitelju kako bi generirao i preuzeo privremeni bearer token.

Primjer cUrl zahtjeva koji možete koristiti za pozivanje get-auth-token točke:

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

Napomena: Zamijenite vrijednosti clientId i clientSecret s podacima koje ste dobili od Spotnane.

Spotnana poslužitelj poziva getToken(clientId,clientSecret) metodu na Spotnana IdP-u, koji generira privremeni bearerToken i vraća ga Spotnana poslužitelju.
Spotnana poslužitelj šalje taj bearer token kao JSON odgovor korisniku API-ja.

Nakon što korisnik API-ja primi bearer token, svi daljnji zahtjevi prema Spotnana API-jima (npr. Trip API-ji) moraju sadržavati bearer token u zaglavlju za autorizaciju.

Napomena: API točka get-auth-token(clientId, clientSecret) ima ograničenje od 100 poziva u 5 minuta.

Autentikacija putem iFrame-a

iFrame ili ugrađeno rješenje podrazumijeva da partneri ugrađuju Spotnana UI u svoje korisničko sučelje, što znači da korisnici pristupaju Spotnani kroz partnerovo sučelje. U ovom slučaju, autentikacija korisnika odvija se putem razmjene tokena između sustava partnera i Spotnane.

Napomena: Kod autentikacije putem iFrame-a, korisnika koji se prijavljuje nazivamo pozivatelj. Ovo omogućuje posebne scenarije gdje se API/strojni korisnik prijavljuje i traži pristupni token za drugog korisnika. Takav API/strojni korisnik može koristiti administratorske podatke TMC-a za izravno povezivanje sa Spotnana poslužiteljem. Stoga ćemo koristiti pojam pozivatelj kao opći izraz, koji može označavati korisnika koji se prijavljuje na vlastiti profil ili API/strojnog korisnika koji traži pristupni token za drugog korisnika.

Sljedeći dijagram prikazuje kako se tijek autentikacije odvija putem razmjene tokena između Spotnane i partnerovih poslužitelja.

Slika: Dijagram slijeda koji prikazuje autentikaciju putem iFrame-a i razmjene tokena.

Korak	Tijek
Pozivatelj se prijavljuje koristeći Partner UI.
1	Partner UI prikazuje Spotnana UI putem iFrame-a.
2	Spotnana UI šalje zahtjev partner UI-ju putem post poruke kako bi preuzeo tokene. Zahtjev se šalje s `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI šalje API zahtjev partner poslužitelju kako bi preuzeo OAuth token, čime započinje sljedeće korake u tijeku autentikacije.
3 a	Partner poslužitelj poziva Spotnana poslužitelj koristeći korisničke vjerodajnice i subject token kao parametre. Spotnana poslužitelj provjerava je li zahtjev poslao API/strojni korisnik.
3 b	Spotnana poslužitelj poziva partner poslužitelj radi preuzimanja e-mail adrese pozivatelja. E-mail adresa se dohvaća i vraća Spotnana poslužitelju, koji ju koristi za identifikaciju korisnika.
3 c	Odgovor na API zahtjev iz koraka 1 šalje Spotnana poslužitelj partner poslužitelju, a on dalje šalje access token i refresh token partner UI-ju. Ti podaci se zatim prosljeđuju Partner UI-ju.
4	Partner UI šalje token Spotnana UI-ju putem post poruke s `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI šalje API zahtjev Spotnana poslužitelju radi generiranja i preuzimanja novog bearer tokena. Spotnana poslužitelj generira bearer token i vraća ga Spotnana UI-ju. Napomena: Uspješno kreiran bearer token znači da je korisnik autentificiran i može pristupiti Spotnani.
6	Nakon što je korisnik autentificiran u koraku 3, svi daljnji API zahtjevi moraju sadržavati bearer token, `orgId`i `tmcId` u zaglavlju zahtjeva. Bearer token se provjerava u svim dolaznim API zahtjevima, a odgovor se vraća Spotnana UI-ju.

Autentikacija putem autorizacijskog koda

Sljedeći dijagram prikazuje kako se tijek autentikacije odvija korištenjem autorizacijskog koda.

Slika: Dijagram slijeda koji prikazuje autentikaciju putem autorizacijskog koda.

Korak	Tijek
1	Partner UI poziva partner poslužitelj radi preuzimanja autorizacijskog koda za pozivatelja koji se prijavljuje. Kod se dohvaća i vraća partner UI-ju.
2	Partner UI šalje zahtjev Spotnana UI-ju koristeći prilagođeni redirect URL koji sadrži `tmcId` i `authCode` kao parametre.
3	Spotnana UI šalje POST API zahtjev Spotnana poslužitelju koristeći `v2/auth/token/companies/<tmcId>(authCode)` API točku.
3 a	Spotnana poslužitelj šalje zahtjev partner poslužitelju radi preuzimanja korisnikovog `pid` korištenjem auth koda. Korisnikov `pid` se dohvaća i šalje Spotnana poslužitelju.
3 b	Spotnana poslužitelj generira access token i refresh token te ih šalje Spotnana UI-ju.
4	Spotnana UI šalje zahtjev Spotnana poslužitelju koristeći access token i refresh token radi generiranja i preuzimanja bearer tokena. Bearer token se generira i šalje Spotnana UI-ju. Napomena: Uspješno kreiran bearer token znači da je korisnik autentificiran i može pristupiti Spotnani.
5	Nakon što je korisnik autentificiran u koraku 4, svi daljnji API zahtjevi moraju sadržavati bearer token, `orgId`i `tmcId` u zaglavlju zahtjeva. Bearer token se provjerava u svim dolaznim API zahtjevima, a odgovor se vraća Spotnana UI-ju.

Napomena: Ovaj način autentikacije nije moguće koristiti u situacijama kada TMC administrator dopušta više korisnika s istom e-mail adresom za prijavu.

Autentikacija između strojeva (M2M)

M2M autentikacija je prikladna kada aplikacija klijenta pristupa callback URL-u treće strane radi generiranja accessToken za korisnika. Sljedeći dijagram prikazuje tijek M2M autentikacije.

Slika: Dijagram slijeda koji prikazuje tijek M2M autentikacije.

Korak	Tijek
Javni ključevi svih aplikacija uključenih u autentikaciju sinkroniziraju se između Spotnana poslužitelja i Spotnana IdP-a. Ti ključevi će se kasnije koristiti za provjeru pristupnog tokena u tijeku autentikacije.
1	Partner poslužitelj šalje API zahtjev na `/oauth2/token(clientId,clientSecret)` na Spotnana IdP-u radi generiranja bearer tokena. Novi bearer token vraća se partner poslužitelju.
2	Partner poslužitelj šalje API zahtjev na callback URL treće strane radi generiranja access tokena za korisnika. Access token se generira i šalje Spotnana poslužitelju.
3	Spotnana poslužitelj provjerava potpis access tokena koristeći ranije sinkronizirane javne ključeve. Također provjerava `claim_id` čime potvrđuje identitet partnera. Access token se zatim šalje partner poslužitelju radi autentikacije korisnika.