Spotnana autentimisprotsessid – Ülevaade

Looja: Ashish Chaudhary, Muudetud P, 5 Okt kell 6:14 autor Ashish Chaudhary

Spotnana autentimisvood – Ülevaade

SISUKORD

Spotnana autentimisvood – Ülevaade
- Põhikomponendid
- Toetatud autentimisviisid

Spotnana pakub mitmesuguseid autentimisviise, mis võimaldavad partneritel turvaliselt meie platvormiga integreeruda. Käesolevas juhendis antakse ülevaade Spotnana poolt toetatud autentimisviisidest ning selgitatakse nende tööpõhimõtteid. Erinevad kirjeldatud autentimisvood näitavad, kuidas Spotnana tuvastab ja volitab kasutajaid ligipääsuks ettevõtte tasemel kaitstud ressurssidele (ehk kasutaja ettevõtte Spotnana platvormil olevatele andmetele).

Põhikomponendid

Enne alustamist tutvuge selle loeteluga, kus on selgitatud dokumentatsioonis mainitud süsteemi põhikomponendid.

Spotnana kasutajaliides(Spotnana User Interface) Spotnana veebipõhine kasutajaliides (ehk Online Booking Tool) või Spotnana mobiilirakendus. Täpsemalt viitab see sisselogimislehele, mis käivitab autentimisprotsessi, kui kasutaja logib sisse või loob uue konto.
Spotnana server Spotnana taustasüsteem, mida kasutatakse autentimiseks (näiteks kasutajale ligipääsu andmiseks või tema andmete turvaliseks salvestamiseks ja töötlemiseks).
Partneri kasutajaliides (Partner's User Interface) Partneri poolt kasutatav kasutajaliides (ehk partneri veebirakendus), mille kaudu pääsetakse Spotnana platvormile. Näiteks iFrame-põhise autentimise korral on Spotnana platvorm partneri kasutajaliidesesse sisse ehitatud ning kasutajad pääsevad Spotnanasse partneri liidese kaudu.
Partneri server Partnerite poolt kasutatavad taustaserverid, mille abil nad Spotnanaga liidestuvad.
Spotnana IdP (Spotnana Identity Provider) Spotnana sisemine teenus, mis haldab kasutajate identiteeti ja volitusi.
Partneri IdP Partnerite poolt kasutatavad kolmanda osapoole identiteedipakkujad (IdP), näiteks Google või Azure.
OBT Spotnana Online Booking Tool (OBT), millele pääseb ligi aadressil https://app.spotnana.com/
Subject token iFrame-põhise (või token exchange) autentimise korral tähistab subject token kasutaja identiteeti. Selle tokeni abil tuvastatakse kasutaja ja antakse talle ligipääs Spotnana platvormile.
Access token Õigusetõend (OAuth), mida partneri rakendus kasutab kaitstud ressurssidele ligipääsuks kasutaja nimel. See on ajutine volituse võti, mis võimaldab teha API päringuid ilma kasutaja paroole avaldamata.
Refresh token Pikema elueaga õigusetõend, mille abil saab taotleda uusi access token’eid ilma, et kasutaja peaks uuesti sisse logima. See väljastatakse tavaliselt koos access token’iga esimese sisselogimise käigus.
Kliendi mandaadid Andmed, mis antakse kasutajatele, kes ühenduvad otse Spotnana API-dega (st unikaalne clientId ja clientSecret).
PID (isiklik identifikaator) Kasutajale loodud isiklik identifikaator. Selle abil tuuakse kasutaja andmed Spotnana serverist.
orgId Spotnana poolt kasutaja organisatsioonile määratud unikaalne identifikaator.
tmcId Spotnana poolt reisihaldusettevõttele (TMC) määratud unikaalne identifikaator.

Toetatud autentimisviisid

Spotnana toetab järgmisi autentimisviise:

Paroolipõhine autentimine
- Olemasolev kasutaja
- Uus kasutaja
IdP-põhine autentimine
API-põhine autentimine
iFrame-põhine autentimine
Autentimiskoodi-põhine autentimine
Masin-masin (M2M) autentimine

Paroolipõhine autentimine

Paroolipõhise autentimise korral algatab ja juhib autentimisprotsessi Spotnana kasutajaliides (st OBT sisselogimis- või registreerimisleht) koostöös Spotnana taustasüsteemidega. Sõltuvalt sellest, kas kasutaja logib sisse olemasoleva profiiliga või loob uue, on protsessis erinevused. Mõlemat autentimisvoogu on allpool kirjeldatud koos joonistega.

Olemasolev kasutaja

Järgnev joonis ja sammud selgitavad, kuidas Spotnana kasutajaliides suhtleb taustateenustega olemasoleva kasutaja autentimiseks.

Joonis: Olemasoleva kasutaja paroolipõhise autentimise protsessi kirjeldav joonis.

Samm	Voo kirjeldus
Olemasolev kasutaja logib sisse OBT või Spotnana mobiilirakenduse kaudu, kasutades oma e-posti aadressi.
1	Spotnana kasutajaliides saadab Spotnana serverisse API-päringu, et tuua kasutaja autentimisseaded. Päringus on kasutaja sisselogimisandmed. Vastus sisaldab kasutaja `tmcId`, `orgId`ja `authProviderType`.
2	Spotnana kasutajaliides saadab Spotnana IdP-le API-päringu, kus on `clientId`, e-posti aadress ja parool. Spotnana IdP loob uue bearer token’i ja saadab selle kasutajaliidesele tagasi. Selle sammuga autentitakse kasutaja.
3	Pärast edukat autentimist (samm 2) peavad kõik järgmised API-päringud sisaldama bearer token’it, `orgId`ja `tmcId` päringu päises. Kõikidesse Spotnana API-päringutesse lisatud bearer token kontrollitakse ning vastus saadetakse kasutajaliidesele tagasi.

Uus kasutaja

Järgnev joonis ja sammud selgitavad, kuidas Spotnana kasutajaliides suhtleb taustateenustega uue kasutaja (või kasutaja, kes soovib parooli lähtestada) autentimiseks.

Joonis: Uue kasutaja paroolipõhise autentimise protsessi kirjeldav joonis.

Samm	Voo kirjeldus
Uus kasutaja sisestab OBT sisselogimislehel oma e-posti aadressi ja vajutab Next.
1	Spotnana kasutajaliides saadab Spotnana serverisse API-päringu, et tuua kasutaja autentimisseaded. Päringus on kasutaja sisselogimisandmed. Vastus sisaldab kasutaja `tmcId`, `orgId`ja `authProviderType`.
1 a	Kasutaja sisestab uue parooli ja vajutab Next.
2	Spotnana kasutajaliides saadab Spotnana IdP-le API-päringu kasutaja registreerimiseks koos `clientId`, e-posti aadressi ja uue parooliga. Pärast andmete registreerimist saadetakse kasutajale ühekordne parool (OTP) tema e-posti aadressile.
3	Kasutaja sisestab OTP Spotnana kasutajaliideses ja vajutab Verify. Spotnana kasutajaliides saadab Spotnana IdP-le päringu OTP kontrollimiseks ja bearer token’i loomiseks. Bearer token luuakse ja saadetakse Spotnana kasutajaliidesele tagasi. See kinnitab, et kasutaja autentimine õnnestus ning ta saab Spotnana platvormile ligi.
4	Pärast edukat autentimist (samm 3) peavad kõik järgmised API-päringud sisaldama bearer token’it, `orgId`ja `tmcId` päringu päises. Kõikidesse Spotnana API-päringutesse lisatud bearer token kontrollitakse ning vastus saadetakse kasutajaliidesele tagasi.

IdP-põhine autentimine

Spotnana toetab autentimist erinevate IdP-de kaudu, nagu Google, Azure ja kohandatud IdP-d OpenID Connecti või SAML protokollide abil. Järgnev joonis ja sammud selgitavad IdP-põhist autentimisvoogu.

Joonis: IdP-põhise autentimisvoo kirjeldav joonis.

Samm	Voo kirjeldus
Kasutaja logib sisse OBT või Spotnana mobiilirakenduse kaudu, kasutades oma e-posti aadressi.
1	Spotnana kasutajaliides saadab Spotnana serverisse API-päringu, et tuua kasutaja autentimisseaded. Päringus on kasutaja sisselogimisandmed. Vastus sisaldab kasutaja `tmcId`, `orgId`ja `authProviderType`.
2	Spotnana kasutajaliides suunab päringu Spotnana IdP-sse.
3	Spotnana IdP suunab päringu edasi partneri IdP-sse. Sellega algab kasutaja autentimine partneri IdP kaudu. Märkus: Iga suunamise korral tagastatakse vastusena staatusekood 302, mis näitab aadressi muutust.
4	Spotnana IdP ja partneri IdP vahel luuakse ühendus, et kontrollida kasutaja autentimist partneri IdP kaudu. Märkus: Selle ühenduse käigus saadab Spotnana IdP `clientId` ja `clientSecret` vormindatult (URL-encoded) API-päringuga partneri IdP-sse. Kui partneri IdP ei toeta seda andmeformaati, saab Spotnana server vajadusel andmed partneri IdP jaoks sobivasse vormi teisendada.
5	Partneri IdP autentib kasutaja edukalt. Märkus: Pärast seda sammu tuleb kasutajaprofiil veel bearer token’iga üle kontrollida.
5 a	Pärast edukat autentimist saadab partneri IdP vastuse Spotnana IdP-le.
5 b	Spotnana IdP loob kasutajaprofiilile unikaalse koodi ja saadab selle Spotnana kasutajaliidesele.
6	Spotnana kasutajaliides saadab Spotnana IdP-le API-päringu koos `clientID` ja eelmises etapis (5b) saadud koodiga. Spotnana IdP loob uue bearer token’i ja saadab selle kasutajaliidesele. Märkus: Bearer token’i edukas loomine kinnitab, et kasutaja on autentitud ning tal on Spotnanasse ligipääs.
7	Pärast edukat autentimist (samm 6) peavad kõik järgmised API-päringud sisaldama bearer token’it, `orgId`ja `tmcId` päringu päises. Kõikidesse Spotnana API-päringutesse lisatud bearer token kontrollitakse ning vastus saadetakse kasutajaliidesele tagasi.

API-põhine autentimine

Partnerid, kes kasutavad Spotnana API-sid ühenduseks Spotnana platvormiga, saavad kasutada meie autentimise lõpp-punkti, et luua oma kasutajatele bearer token. Järgnev joonis illustreerib API-põhise autentimise protsessi.

Joonis: API-põhise autentimise protsessi kirjeldav joonis.

Samm Voo kirjeldus

Samm	Voo kirjeldus
1	API kasutaja teeb POST päringu `get-auth-token(clientId,clientSecret)` lõpp-punkti Spotnana serveris, et luua ja saada ajutine bearer token. Siin on näide cUrl päringust, mida saab kasutada `get-auth-token` lõpp-punkti kutsumisel: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Märkus: Asendage `clientId` ja `clientSecret` vastavate Spotnanast saadud mandaadiga.
2	Spotnana server kutsub `getToken(clientId,clientSecret)` meetodit Spotnana IdP-s, mis loob ajutise `bearerToken` ja saadab selle Spotnana serverile tagasi. Spotnana server saadab selle bearer token’i API kasutajale JSON-vastusega.

API kasutaja teeb POST päringu get-auth-token(clientId,clientSecret) lõpp-punkti Spotnana serveris, et luua ja saada ajutine bearer token.

Siin on näide cUrl päringust, mida saab kasutada get-auth-token lõpp-punkti kutsumisel:

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

Märkus: Asendage clientId ja clientSecret vastavate Spotnanast saadud mandaadiga.

Spotnana server kutsub getToken(clientId,clientSecret) meetodit Spotnana IdP-s, mis loob ajutise bearerToken ja saadab selle Spotnana serverile tagasi.
Spotnana server saadab selle bearer token’i API kasutajale JSON-vastusega.

Pärast bearer token’i saamist tuleb kõikides Spotnana API-de (nt Trip API-d) päringutes lisada bearer token päisesse volituseks.

Märkus: The get-auth-token(clientId, clientSecret) lõpp-punktil on piirang – 100 API päringut 5 minuti jooksul.

iFrame-põhine autentimine

iFrame või manustatud lahendus tähendab, et partnerid lisavad Spotnana kasutajaliidese omaenda kasutajaliidesesse, mistõttu pääsevad kasutajad Spotnanasse läbi partneri liidese. Selles olukorras toimub kasutaja autentimine token’ite vahetuse kaudu partneri ja Spotnana süsteemide vahel.

Märkus: iFrame-põhise autentimise puhul nimetatakse sisse logivat kasutajat üldiselt caller. See võimaldab olukordi, kus API/masinkasutaja logib sisse ja taotleb teisele kasutajale access token’it. Selline kasutaja võib kasutada TMC administraatori õigusi, et otse Spotnana serveriga ühenduda. Seetõttu kasutataksegi mõistet caller üldmõistena, mis võib tähendada nii enda profiiliga sisse logivat kasutajat kui ka masinkasutajat, kes taotleb token’it teisele kasutajale.

Järgnev joonis näitab, kuidas Spotnana ja partneri serverite vahel toimub autentimisvoog token’ite vahetuse teel.

Joonis: iFrame-põhise autentimise protsessi kirjeldav joonis token’ite vahetusega.

Samm	Voo kirjeldus
Caller logib sisse partneri kasutajaliidese kaudu.
1	Partneri kasutajaliides kuvab Spotnana kasutajaliidese iFrame’i abil.
2	Spotnana kasutajaliides saadab partneri kasutajaliidesele post message’i kaudu päringu token’ite saamiseks. Päringus on parameeter `type=TOKEN_EXCHANGE_REQUEST`.
3	Partneri kasutajaliides saadab API-päringu partneri serverisse, et saada OAuth token, alustades järgmisi autentimissamme.
3 a	Partneri server pöördub Spotnana serveri poole, kasutades kasutaja mandaate ja subject token’it parameetritena. Spotnana server kontrollib, kas päring tuleb API/masinkasutajalt.
3 b	Spotnana server pöördub partneri serveri poole, et saada subject’i (ehk caller’i) e-posti aadress. E-posti aadress saadetakse Spotnana serverile, kes tuvastab kasutaja selle põhjal.
3 c	Spotnana server saadab partneri serverile vastuseks access token’i ja refresh token’i. Need andmed edastatakse edasi partneri kasutajaliidesele.
4	Partneri kasutajaliides saadab token’i Spotnana kasutajaliidesele post message’iga, millel on `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana kasutajaliides saadab Spotnana serverisse API-päringu, et luua ja saada uus bearer token. Spotnana server loob bearer token’i ja saadab selle kasutajaliidesele tagasi. Märkus: Bearer token’i edukas loomine kinnitab, et kasutaja on autentitud ning tal on Spotnanasse ligipääs.
6	Pärast edukat autentimist (samm 3) peavad kõik järgmised API-päringud sisaldama bearer token’it, `orgId`ja `tmcId` päringu päises. Kõikidesse Spotnana API-päringutesse lisatud bearer token kontrollitakse ning vastus saadetakse kasutajaliidesele tagasi.

Autentimiskoodi-põhine autentimine

Järgnev joonis näitab, kuidas autentimisvoog toimub kasutades autoriseerimiskoodi.

Joonis: Autentimiskoodi-põhise autentimise protsessi kirjeldav joonis.

Samm	Voo kirjeldus
1	Partneri kasutajaliides pöördub partneri serveri poole, et saada caller’i jaoks autentimiskood. Kood saadetakse partneri kasutajaliidesele tagasi.
2	Partneri kasutajaliides saadab Spotnana kasutajaliidesele päringu kohandatud suunamislingiga, kus on parameetritena `tmcId` ja `authCode` .
3	Spotnana kasutajaliides teeb POST API-päringu Spotnana serverisse, kasutades lõpp-punkti `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	Spotnana server saadab partneri serverile päringu, et saada kasutaja `pid` autentimiskoodi alusel. Kasutaja `pid` saadakse kätte ja edastatakse Spotnana serverile.
3 b	Spotnana server loob access token’i ja refresh token’i ning saadab need Spotnana kasutajaliidesele.
4	Spotnana kasutajaliides saadab Spotnana serverile päringu access token’i ja refresh token’i alusel, et saada bearer token. Bearer token luuakse ja saadetakse Spotnana kasutajaliidesele. Märkus: Bearer token’i edukas loomine kinnitab, et kasutaja on autentitud ning tal on Spotnanasse ligipääs.
5	Pärast edukat autentimist (samm 4) peavad kõik järgmised API-päringud sisaldama bearer token’it, `orgId`ja `tmcId` päringu päises. Kõikidesse Spotnana API-päringutesse lisatud bearer token kontrollitakse ning vastus saadetakse kasutajaliidesele tagasi.

Märkus: Seda autentimisvoogu ei saa kasutada olukorras, kus TMC administraator lubab mitmel kasutajal sama e-posti aadressiga sisse logida.

Masin-masin (M2M) autentimine

M2M autentimine sobib olukordadesse, kus kliendirakendus pöördub kolmanda osapoole callback-aadressile, et luua kasutajale accessToken . Järgnev joonis kirjeldab M2M autentimisvoogu.

Joonis: M2M autentimisvoo kirjeldav joonis.

Samm	Voo kirjeldus
Kõik autentimises kasutatavate rakenduste avalikud võtmed sünkroniseeritakse Spotnana serveri ja Spotnana IdP vahel. Neid kasutatakse hiljem access token’i kontrollimiseks autentimisprotsessis.
1	Partneri server saadab API-päringu aadressile `/oauth2/token(clientId,clientSecret)` Spotnana IdP-s, et luua bearer token. Uus bearer token saadetakse partneri serverile tagasi.
2	Partneri server saadab API-päringu kolmanda osapoole callback-aadressile, et luua kasutajale access token. See access token luuakse ja saadetakse Spotnana serverile.
3	Spotnana server kontrollib access token’i allkirja varem sünkroniseeritud avalike võtmete abil. Samuti kontrollitakse `claim_id` mis kinnitab partneri identiteedi. Access token saadetakse partneri serverile kasutaja autentimiseks.