Pregled Spotnana procesa autentifikacije

Kreirao Ashish Chaudhary, Izmijenjeno na Sat, 4 Okt u 10:22 POSLIJEPODNE od Ashish Chaudhary

Spotnana tokovi autentifikacije – Pregled

SADRŽAJ

Spotnana tokovi autentifikacije – Pregled
- Ključne komponente
- Podržane metode autentifikacije

Spotnana omogućava više metoda autentifikacije kako bi partnerima olakšala sigurnu integraciju sa našom platformom. U ovom dokumentu dat je pregled trenutno podržanih metoda autentifikacije na Spotnani, uz detaljna pojašnjenja svakog toka procesa. Ovi tokovi autentifikacije pokazuju na koji način Spotnana provjerava identitet i daje ovlaštenja korisnicima za pristup zaštićenim resursima na nivou organizacije (odnosno, resursima koji pripadaju kompaniji korisnika na Spotnana platformi).

Ključne komponente

Prije nego što počnete, preporučujemo da pročitate ovaj spisak definicija osnovnih sistemskih komponenti koje se pominju u dokumentaciji.

Spotnana UI(Spotnana korisnički interfejs) Odnosi se na Spotnana web aplikaciju (Online Booking Tool) ili Spotnana mobilnu aplikaciju. Konkretno, misli se na stranicu za prijavu, koja pokreće frontend tok autentifikacije kada se korisnik prijavljuje ili kreira novi nalog.
Spotnana server Odnosi se na Spotnana serversku pozadinu koja služi za autentifikaciju (npr. za ovlaštenje korisnika za pristup određenim resursima te sigurno čuvanje i obradu korisničkih podataka).
Partner UI (Korisnički interfejs partnera) Korisnički interfejs (frontend aplikacija) koji partneri koriste za pristup Spotnana platformi. Na primjer, kod autentifikacije putem iFrame-a, Spotnana platforma je ugrađena u korisnički interfejs partnera i njihovi korisnici pristupaju Spotnani preko tog interfejsa.
Partner server Odnosi se na jedan ili više serverskih sistema koje naši partneri koriste za integraciju sa Spotnanom.
Spotnana IdP (Spotnana provajder identiteta) Odnosi se na interni Spotnana servis za upravljanje korisničkim identitetima i ovlaštenjima.
Partner IdP Treći provajderi identiteta (IdP) koje koriste partneri. Najčešći su Google i Azure.
OBT Spotnana alat za online rezervacije (OBT), kojem možete pristupiti na https://app.spotnana.com/
Subject token U iFrame autentifikaciji (ili autentifikaciji razmjenom tokena), subject token predstavlja identitet korisnika. Ovaj token se koristi za pretragu korisničkih podataka i ovlaštenje pristupa Spotnana platformi.
Access token Ovo je privremena akreditacija (OAuth) koju partnerska aplikacija koristi za pristup zaštićenim resursima u ime korisnika. Omogućava aplikacijama da šalju API zahtjeve bez izlaganja korisničkih vjerodajnica.
Refresh token Ovo je dugotrajna akreditacija kojom se mogu dobiti novi access tokeni bez ponovne autentifikacije korisnika. Obično se izdaje zajedno sa access tokenom prilikom prve prijave.
Client credentials Podaci koji se daju korisnicima koji direktno pristupaju Spotnana API-jima (npr. jedinstveni clientId i clientSecret).
PID (Lični identifikator) Lični identifikator koji se kreira za korisnika. PID se koristi za dohvat korisničkih podataka sa Spotnana servera.
orgId Jedinstveni identifikator koji Spotnana dodjeljuje organizaciji korisnika.
tmcId Jedinstveni identifikator koji Spotnana dodjeljuje TMC-u (Travel Management Company).

Podržane metode autentifikacije

Spotnana podržava sljedeće metode autentifikacije:

Autentifikacija putem lozinke
- Postojeći korisnik
- Novi korisnik
Autentifikacija putem IdP-a
Autentifikacija putem API-ja
Autentifikacija putem iFrame-a
Autentifikacija putem auth koda
Autentifikacija između mašina (M2M)

Autentifikacija putem lozinke

Kod autentifikacije putem lozinke, Spotnana UI (stranica za prijavu ili registraciju u OBT-u) pokreće i upravlja procesom autentifikacije sa Spotnana serverskom pozadinom. Ovaj pristup može imati dva toka, u zavisnosti od toga da li se korisnik prijavljuje sa postojećim profilom ili kreira novi. Detaljan prikaz oba toka dat je u nastavku kroz sekvencijske dijagrame.

Postojeći korisnik

Sljedeći dijagram i koraci objašnjavaju kako Spotnana UI komunicira sa serverskim servisima radi autentifikacije postojećeg korisnika.

Slika: Sekvencijski dijagram koji prikazuje tok autentifikacije putem lozinke za postojeće korisnike.

Korak	Tok
Postojeći korisnik se prijavljuje putem OBT-a ili Spotnana mobilne aplikacije koristeći svoju email adresu.
1	Spotnana UI šalje API zahtjev Spotnana serveru kako bi preuzeo informacije o konfiguraciji autentifikacije za korisnika. U zahtjevu se šalju korisnički podaci za prijavu. Odgovor sadrži korisnikov `tmcId`, `orgId`, i `authProviderType`.
2	Spotnana UI zatim šalje API zahtjev Spotnana IdP-u koristeći `clientId`, email i lozinku. Spotnana IdP generiše novi bearer token i vraća ga Spotnana UI-ju. Ovim korakom korisnik je autentificiran.
3	Nakon što je korisnik autentificiran u prethodnom koraku, svi naredni 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

Sekvencijski dijagram i koraci u nastavku objašnjavaju kako Spotnana UI komunicira sa serverskim servisima radi autentifikacije novog korisnika (ili postojećeg korisnika koji pokušava resetovati lozinku).

Slika: Sekvencijski dijagram koji prikazuje tok autentifikacije putem lozinke za nove korisnike.

Korak	Tok
Novi korisnik unosi svoju email adresu na stranici za prijavu u Spotnana OBT i klikne na Dalje.
1	Spotnana UI šalje API zahtjev Spotnana serveru kako bi preuzeo informacije o konfiguraciji autentifikacije za korisnika. U zahtjevu se šalju korisnički podaci za prijavu. Odgovor sadrži korisnikov `tmcId`, `orgId`, i `authProviderType`.
1 a	Korisnik unosi novu lozinku i klikne na Dalje.
2	Spotnana UI šalje API zahtjev Spotnana IdP-u za registraciju korisnika sa njegovim `clientId`, email adresom i novom lozinkom. Nakon registracije podataka, korisniku se na email šalje jednokratna šifra (OTP).
3	Korisnik unosi OTP u Spotnana UI i klikne na Potvrdi. Spotnana UI šalje zahtjev Spotnana IdP-u radi provjere OTP-a i generisanja bearer tokena za prijavu. Bearer token se generiše i vraća Spotnana UI-ju. Ovo označava uspješnu autentifikaciju korisnika za pristup Spotnana platformi koristeći bearer token.
4	Nakon što je korisnik autentificiran u prethodnom koraku, svi naredni 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.

Autentifikacija putem IdP-a

Spotnana podržava autentifikaciju putem IdP-ova kao što su Google, Azure i prilagođeni IdP-ovi koristeći OpenID Connect i SAML protokole. Sekvencijski dijagram i koraci u nastavku prikazuju tok autentifikacije putem IdP-a.

Slika: Sekvencijski dijagram koji prikazuje tok autentifikacije putem IdP-a.

Korak	Tok
Korisnik se prijavljuje putem OBT-a ili Spotnana mobilne aplikacije koristeći svoju email adresu.
1	Spotnana UI šalje API zahtjev Spotnana serveru kako bi preuzeo informacije o konfiguraciji autentifikacije za korisnika. U zahtjevu se šalju korisnički podaci za prijavu. 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 se pokreće autentifikacija korisnika putem IdP-a. Napomena: Za svako preusmjeravanje, vraća se status kod 302, što označava da je zahtjev preusmjeren na drugu adresu.
4	Uspostavlja se veza između Spotnana IdP-a i partnerovog IdP-a, kako bi se provjerilo da li je korisnik uspješno autentificiran kod partnera. Napomena: Tokom ove veze, Spotnana IdP šalje `clientId` i `clientSecret` kao podatke kodirane putem URL obrasca koristeći API poziv prema partnerovom IdP-u. Ako IdP serveri ne mogu obraditi ovaj format, Spotnana server može poslužiti kao posrednik i prevesti podatke u format koji partnerov IdP prepoznaje.
5	Partnerov IdP uspješno autentificira korisnika. Napomena: Nakon ovog koraka, korisnički profil mora još proći provjeru bearer tokena.
5 a	Nakon uspješne autentifikacije, odgovor sa partnerovog IdP-a šalje se Spotnana IdP-u.
5 b	Spotnana IdP generiše 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 primljen u koraku 5(b). Spotnana IdP generiše 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 prethodnom koraku, svi naredni 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.

Autentifikacija putem API-ja

Partneri koji koriste Spotnana API-je za povezivanje sa platformom mogu koristiti naš autentifikacijski endpoint za generisanje bearer tokena za svoje korisnike. Sljedeći sekvencijski dijagram prikazuje tok autentifikacije za svakog partnera koji koristi autentifikaciju putem API-ja.

Slika: Sekvencijski dijagram koji prikazuje autentifikaciju putem API-ja.

Korak Tok

Korak	Tok
1	API korisnik šalje POST zahtjev na `get-auth-token(clientId,clientSecret)` API endpoint na Spotnana serveru kako bi generisao i preuzeo privremeni bearer token. Evo primjera cUrl zahtjeva koji možete koristiti za pozivanje `get-auth-token` endpointa: 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 za `clientId` i `clientSecret` sa podacima koje ste dobili od Spotnane.
2	Spotnana server poziva `getToken(clientId,clientSecret)` metodu na Spotnana IdP-u, koja generiše privremeni `bearerToken` i vraća ga Spotnana serveru. Spotnana server šalje ovaj bearer token kao JSON odgovor API korisniku.

API korisnik šalje POST zahtjev na get-auth-token(clientId,clientSecret) API endpoint na Spotnana serveru kako bi generisao i preuzeo privremeni bearer token.

Evo primjera cUrl zahtjeva koji možete koristiti za pozivanje get-auth-token endpointa:

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 za clientId i clientSecret sa podacima koje ste dobili od Spotnane.

Spotnana server poziva getToken(clientId,clientSecret) metodu na Spotnana IdP-u, koja generiše privremeni bearerToken i vraća ga Spotnana serveru.
Spotnana server šalje ovaj bearer token kao JSON odgovor API korisniku.

Kada API korisnik dobije bearer token, svi naredni zahtjevi prema Spotnana API-jima (npr. Trip API-ji) moraju sadržavati bearer token u zaglavlju radi autorizacije.

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

Autentifikacija putem iFrame-a

iFrame ili ugrađeno rješenje znači da partneri ugrađuju Spotnana UI u svoj korisnički interfejs, tako da korisnici pristupaju Spotnani preko partner UI-ja. U ovom slučaju, autentifikacija korisnika se vrši razmjenom tokena između sistema partnera i Spotnane.

Napomena: Kod iFrame autentifikacije, korisnik koji se prijavljuje naziva se pozivaoc. Ovo omogućava specifične scenarije u kojima se API/mašinski korisnik prijavljuje i traži access token za drugog korisnika. Takav API/mašinski korisnik može koristiti administratorske podatke TMC-a za direktno povezivanje sa Spotnana serverom. Zbog toga koristimo termin pozivaoc kao opći pojam, koji može označavati korisnika koji se prijavljuje na svoj profil ili API/mašinskog korisnika koji traži access token za nekog drugog.

Sljedeći sekvencijski dijagram prikazuje kako se tok autentifikacije odvija razmjenom tokena između Spotnane i serverskih sistema partnera.

Slika: Sekvencijski dijagram koji prikazuje autentifikaciju putem iFrame-a koristeći razmjenu tokena.

Korak	Tok
Pozivaoc se prijavljuje putem Partner UI-ja.
1	Partner UI prikazuje Spotnana UI unutar iFrame-a.
2	Spotnana UI šalje zahtjev partner UI-ju putem post message poruke radi preuzimanja tokena. Zahtjev se šalje sa `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI šalje API zahtjev partner serveru radi preuzimanja OAuth tokena i time pokreće naredne korake u procesu autentifikacije.
3 a	Partner server poziva Spotnana server koristeći korisničke podatke i subject token kao parametre. Spotnana server provjerava da li je zahtjev poslao API/mašinski korisnik.
3 b	Spotnana server poziva partner server radi preuzimanja email adrese subjecta (pozivaoca). Email se dohvaća i vraća Spotnana serveru, koji ga koristi za identifikaciju korisnika.
3 c	Odgovor na API zahtjev iz koraka 1 Spotnana server šalje partner serveru i sadrži access token i refresh token. Ovi podaci se zatim šalju Partner UI-ju.
4	Partner UI šalje token Spotnana UI-ju putem post message poruke sa `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI šalje API zahtjev Spotnana serveru radi generisanja i preuzimanja novog bearer tokena. Spotnana server generiše 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 naredni 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.

Autentifikacija putem auth koda

Sljedeći sekvencijski dijagram prikazuje kako se tok autentifikacije odvija korištenjem autorizacijskog koda.

Slika: Sekvencijski dijagram koji prikazuje autentifikaciju putem auth koda.

Korak	Tok
1	Partner UI poziva partner server radi preuzimanja auth koda za pozivaoca koji se prijavljuje. Auth kod se preuzima i šalje nazad 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 serveru koristeći `v2/auth/token/companies/<tmcId>(authCode)` API endpoint.
3 a	Spotnana server šalje zahtjev partner serveru radi preuzimanja korisničkog `pid` koristeći auth kod. Korisnički `pid` se preuzima i šalje Spotnana serveru.
3 b	Spotnana server generiše access token i refresh token i šalje ih Spotnana UI-ju.
4	Spotnana UI šalje zahtjev Spotnana serveru koristeći access token i refresh token radi generisanja i preuzimanja bearer tokena za pristup. Bearer token se generiše 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 naredni 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 tok autentifikacije nije moguće koristiti u situacijama kada TMC administrator dozvoljava više korisnika sa istom email adresom za prijavu.

Autentifikacija između mašina (M2M)

M2M metoda autentifikacije je pogodna kada tok autentifikacije podrazumijeva da klijentska aplikacija pristupa trećem callback URL-u radi generisanja accessToken za korisnika. Sljedeći sekvencijski dijagram prikazuje tok M2M autentifikacije.

Slika: Sekvencijski dijagram koji prikazuje tok M2M autentifikacije.

Korak	Tok
Javni ključevi za sve aplikacije koje učestvuju u autentifikaciji sinhroniziraju se između Spotnana servera i Spotnana IdP-a. Ti ključevi će kasnije biti korišteni za provjeru access tokena tokom procesa autentifikacije.
1	Partner server šalje API zahtjev na `/oauth2/token(clientId,clientSecret)` na Spotnana IdP-u radi generisanja bearer tokena. Novi bearer token se vraća partner serveru.
2	Partner server šalje API zahtjev na treći callback URL radi generisanja access tokena za korisnika. Ovaj access token se kreira i šalje Spotnana serveru.
3	Spotnana server provjerava potpis access tokena koristeći javne ključeve koji su prethodno sinhronizirani. Također provjerava `claim_id` čime potvrđuje identitet partnera. Access token se zatim šalje partner serveru radi autentifikacije korisnika.