Spotnanan tunnistautumisprosessit – Yleiskatsaus

Tekijä Ashish Chaudhary, Muokattu Su, 5 Loka klo 9:56 AM tekijä Ashish Chaudhary

Spotnanan tunnistautumisprosessit – Yleiskatsaus

SISÄLLYSLUETTELO

Spotnanan tunnistautumisprosessit – Yleiskatsaus
- Avainkomponentit
- Tukemamme tunnistautumistavat

Spotnana tarjoaa useita erilaisia tunnistautumistapoja, joiden avulla kumppanit voivat liittää palvelunsa turvallisesti meidän alustaan. Tässä ohjeessa käydään läpi Spotnanan tukemat tunnistautumismenetelmät ja niiden kulku vaihe vaiheelta. Näissä tunnistautumisprosesseissa näytetään, miten Spotnana tunnistaa ja valtuuttaa käyttäjät pääsemään organisaatiokohtaisiin suojattuihin tietoihin (eli käyttäjän yrityksen omistamiin resursseihin Spotnana-alustalla).

Avainkomponentit

Ennen kuin aloitat, tutustu tähän listaan, jossa määritellään tämän ohjeen kannalta keskeiset järjestelmän osat.

Spotnana UI(Spotnanan käyttöliittymä) Tarkoittaa Spotnanan verkkoselaimessa toimivaa käyttöliittymää (eli Online Booking Toolia) tai Spotnanan mobiilisovellusta. Käytännössä kyseessä on kirjautumissivu, joka käynnistää tunnistautumisprosessin, kun käyttäjä kirjautuu sisään tai luo uuden tunnuksen.
Spotnana-palvelin Tarkoittaa Spotnanan taustajärjestelmää, jota käytetään tunnistautumiseen (esimerkiksi käyttäjän oikeuksien tarkistamiseen sekä käyttäjätietojen turvalliseen tallentamiseen ja käsittelyyn).
Kumppanin käyttöliittymä (Kumppanin käyttöliittymä) Kumppanin oma käyttöliittymä (eli heidän oma verkkosovelluksensa), jonka kautta Spotnanan palvelua käytetään. Esimerkiksi iFrame-pohjaisessa tunnistautumisessa Spotnanan palvelu upotetaan kumppanin käyttöliittymään, jolloin heidän käyttäjänsä käyttävät Spotnanaa oman käyttöliittymänsä kautta.
Kumppanin palvelin Tarkoittaa yhtä tai useampaa kumppanin taustapalvelinta, joiden avulla Spotnana-integraatio toteutetaan.
Spotnana IdP (Spotnanan tunnistuspalvelu) Tarkoittaa Spotnanan sisäistä palvelua, jolla hallitaan käyttäjien tunnistetietoja ja käyttöoikeuksia.
Kumppanin IdP Kumppanin käyttämät kolmannen osapuolen tunnistuspalvelut (IdP). Yleisiä esimerkkejä ovat Google ja Azure.
OBT Spotnanan Online Booking Tool (OBT), joka löytyy osoitteesta https://app.spotnana.com/
Subject token iFrame- tai token-vaihtoon perustuvassa tunnistautumisessa subject token edustaa käyttäjän henkilöllisyyttä. Tämän avulla haetaan käyttäjän tiedot ja myönnetään pääsy Spotnanan palveluun.
Access token Todistus (OAuth), jonka avulla kumppanisovellus voi käyttää suojattuja resursseja käyttäjän puolesta. Kyseessä on väliaikainen käyttöoikeusavain, jonka avulla sovellukset voivat tehdä API-pyyntöjä paljastamatta käyttäjän salasanaa.
Refresh token Pitkäkestoinen tunniste, jonka avulla voidaan hakea uusia access token -tunnuksia ilman, että käyttäjän tarvitsee kirjautua uudelleen. Tämä annetaan yleensä access tokenin mukana ensimmäisen kirjautumisen yhteydessä.
Client credentials Tiedot, jotka annetaan käyttäjille, jotka yhdistävät suoraan Spotnanan API-rajapintoihin (eli yksilöllinen clientId ja clientSecret).
PID (henkilökohtainen tunniste) Käyttäjälle luotu yksilöllinen tunniste. PID:n avulla haetaan käyttäjän tiedot Spotnanan palvelimelta.
orgId Yksilöllinen tunniste, jonka Spotnana antaa käyttäjän organisaatiolle.
tmcId Yksilöllinen tunniste, jonka Spotnana antaa matkatoimistolle (TMC, Travel Management Company).

Tukemamme tunnistautumistavat

Spotnana tukee seuraavia tunnistautumismenetelmiä:

Salasanaan perustuva tunnistautuminen
- Olemassa oleva käyttäjä
- Uusi käyttäjä
IdP-pohjainen tunnistautuminen
API-pohjainen tunnistautuminen
iFrame-pohjainen tunnistautuminen
Auth code -pohjainen tunnistautuminen
Koneiden välinen (M2M) tunnistautuminen

Salasanaan perustuva tunnistautuminen

Kun käytössä on salasanaan perustuva tunnistautuminen, Spotnanan käyttöliittymä (eli OBT:n kirjautumis- tai rekisteröitymissivu) käynnistää ja hallinnoi tunnistautumista Spotnanan taustapalvelimilla. Prosessi etenee eri tavalla riippuen siitä, kirjautuuko käyttäjä jo olemassa olevalla tunnuksella vai luoko hän uuden tunnuksen. Molemmat vaihtoehdot käydään läpi seuraavissa osioissa vaiheittain ja sekvenssikaavioiden avulla.

Olemassa oleva käyttäjä

Alla oleva sekvenssikaavio ja vaiheet kuvaavat, miten Spotnanan käyttöliittymä ja taustapalvelut toimivat yhdessä, kun olemassa oleva käyttäjä tunnistetaan.

Kuva: Sekvenssikaavio, jossa kuvataan salasanaan perustuva tunnistautuminen olemassa oleville käyttäjille.

Vaihe	Kulku
Olemassa oleva käyttäjä kirjautuu OBT:n tai Spotnanan mobiilisovelluksen kautta sähköpostiosoitteellaan.
1	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan palvelimelle hakeakseen käyttäjän tunnistautumisasetukset. Pyynnössä välitetään käyttäjän kirjautumistiedot. Vastauksessa palautetaan käyttäjän `tmcId`, `orgId`ja `authProviderType`.
2	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan IdP:lle käyttäen `clientId`, sähköpostiosoitetta ja salasanaa. Spotnanan IdP luo uuden bearer tokenin ja palauttaa sen käyttöliittymälle. Tässä vaiheessa käyttäjä tunnistetaan.
3	Kun käyttäjä on tunnistettu vaiheessa 2, kaikki seuraavat API-pyynnöt tulee lähettää siten, että otsikossa on bearer token sekä `orgId`ja `tmcId` . Kaikissa tulevissa API-pyynnöissä bearer token tarkistetaan ja vastaus palautetaan Spotnanan käyttöliittymään.

Uusi käyttäjä

Alla oleva sekvenssikaavio ja vaiheet kuvaavat, miten Spotnanan käyttöliittymä ja taustapalvelut toimivat yhdessä uuden käyttäjän (tai käyttäjän, joka palauttaa salasanansa) tunnistautumisessa.

Kuva: Sekvenssikaavio, jossa kuvataan salasanaan perustuva tunnistautuminen uusille käyttäjille.

Vaihe	Kulku
Uusi käyttäjä syöttää sähköpostiosoitteensa Spotnanan OBT-kirjautumissivulla ja painaa Seuraava.
1	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan palvelimelle hakeakseen käyttäjän tunnistautumisasetukset. Pyynnössä välitetään käyttäjän kirjautumistiedot. Vastauksessa palautetaan käyttäjän `tmcId`, `orgId`ja `authProviderType`.
1 a	Käyttäjä syöttää uuden salasanan ja painaa Seuraava.
2	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan IdP:lle käyttäjän `clientId`, sähköpostiosoitteen ja uuden salasanan kanssa. Tietojen rekisteröinnin jälkeen käyttäjälle lähetetään kertakäyttöinen salasana (OTP) sähköpostiin.
3	Käyttäjä syöttää OTP-koodin Spotnanan käyttöliittymään ja painaa Vahvista. Spotnanan käyttöliittymä lähettää pyynnön Spotnanan IdP:lle vahvistaakseen OTP:n ja luodakseen bearer tokenin kirjautumista varten. Bearer token luodaan ja palautetaan Spotnanan käyttöliittymään. Tämä tarkoittaa, että käyttäjä on tunnistettu ja voi käyttää Spotnanan palvelua bearer tokenilla.
4	Kun käyttäjä on tunnistettu vaiheessa 3, kaikki seuraavat API-pyynnöt tulee lähettää siten, että otsikossa on bearer token sekä `orgId`ja `tmcId` . Kaikissa tulevissa API-pyynnöissä bearer token tarkistetaan ja vastaus palautetaan Spotnanan käyttöliittymään.

IdP-pohjainen tunnistautuminen

Spotnana tukee tunnistautumista IdP-palveluiden kautta, kuten Google, Azure ja muut OpenID Connect- tai SAML-pohjaiset ratkaisut. Alla oleva sekvenssikaavio ja vaiheet kuvaavat IdP-pohjaisen tunnistautumisen kulun.

Kuva: Sekvenssikaavio, jossa kuvataan IdP-pohjainen tunnistautumisprosessi.

Vaihe	Kulku
Käyttäjä kirjautuu OBT:n tai Spotnanan mobiilisovelluksen kautta sähköpostiosoitteellaan.
1	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan palvelimelle hakeakseen käyttäjän tunnistautumisasetukset. Pyynnössä välitetään käyttäjän kirjautumistiedot. Vastauksessa palautetaan käyttäjän `tmcId`, `orgId`ja `authProviderType`.
2	Spotnanan käyttöliittymä ohjaa pyynnön Spotnanan IdP:lle.
3	Spotnanan IdP ohjaa pyynnön kumppanin IdP:lle. Tämä käynnistää käyttäjän tunnistautumisen kumppanin IdP:n kautta. Huom: Jokaisesta uudelleenohjauksesta palautetaan tilakoodi 302, joka kertoo, että pyyntö on ohjattu toiseen osoitteeseen.
4	Spotnanan IdP ja kumppanin IdP muodostavat yhteyden varmistaakseen, että käyttäjä tunnistetaan kumppanin IdP:n toimesta. Huom: Tässä yhteydessä Spotnanan IdP lähettää `clientId` ja `clientSecret` arvot lomakemuotoisena (URL-encoded) datana API-kutsulla kumppanin IdP:lle. Jos IdP-palvelin ei tue tätä muotoa, Spotnanan palvelin voi toimia välittäjänä ja muuntaa tiedot kumppanin IdP:n ymmärtämään muotoon.
5	Kumppanin IdP tunnistaa käyttäjän onnistuneesti. Huom: Tämän jälkeen käyttäjäprofiili täytyy vielä vahvistaa bearer tokenilla.
5 a	Onnistuneen tunnistautumisen jälkeen kumppanin IdP:n vastaus siirtyy Spotnanan IdP:lle.
5 b	Spotnanan IdP luo käyttäjäprofiilille yksilöllisen koodin ja lähettää sen Spotnanan käyttöliittymälle.
6	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan IdP:lle käyttäen `clientID` ja vaiheessa 5(b) saatua koodia. Spotnanan IdP luo uuden bearer tokenin ja lähettää sen Spotnanan käyttöliittymälle. Huom: Bearer tokenin onnistunut luonti tarkoittaa, että käyttäjä on tunnistettu ja saa käyttää Spotnanaa.
7	Kun käyttäjä on tunnistettu vaiheessa 6, kaikki seuraavat API-pyynnöt tulee lähettää siten, että otsikossa on bearer token sekä `orgId`ja `tmcId` . Kaikissa tulevissa API-pyynnöissä bearer token tarkistetaan ja vastaus palautetaan Spotnanan käyttöliittymään.

API-pohjainen tunnistautuminen

Kumppanit, jotka käyttävät Spotnanan API-rajapintoja yhdistääkseen oman järjestelmänsä Spotnanaan, voivat käyttää tunnistautumispäätepistettämme luodakseen bearer tokenin käyttäjilleen. Alla oleva sekvenssikaavio kuvaa, miten API-pohjainen tunnistautuminen etenee.

Kuva: Sekvenssikaavio, jossa kuvataan API-pohjainen tunnistautuminen.

Vaihe Kulku

Vaihe	Kulku
1	API-käyttäjä tekee POST kutsun `get-auth-token(clientId,clientSecret)` API-päätepisteeseen Spotnanan palvelimella saadakseen väliaikaisen bearer tokenin. Tässä esimerkki cUrl-pyynnöstä, jota voit käyttää kutsuessasi `get-auth-token` päätepistettä: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Huom: Vaihda `clientId` ja `clientSecret` -kenttien arvot niihin tunnuksiin, jotka olet saanut Spotnanalta.
2	Spotnanan palvelin kutsuu `getToken(clientId,clientSecret)` metodia Spotnanan IdP:ssä, joka luo väliaikaisen `bearerToken` ja palauttaa sen Spotnanan palvelimelle. Spotnanan palvelin lähettää tämän bearer tokenin API-käyttäjälle JSON-muodossa.

API-käyttäjä tekee POST kutsun get-auth-token(clientId,clientSecret) API-päätepisteeseen Spotnanan palvelimella saadakseen väliaikaisen bearer tokenin.

Tässä esimerkki cUrl-pyynnöstä, jota voit käyttää kutsuessasi get-auth-token päätepistettä:

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

Huom: Vaihda clientId ja clientSecret -kenttien arvot niihin tunnuksiin, jotka olet saanut Spotnanalta.

Spotnanan palvelin kutsuu getToken(clientId,clientSecret) metodia Spotnanan IdP:ssä, joka luo väliaikaisen bearerToken ja palauttaa sen Spotnanan palvelimelle.
Spotnanan palvelin lähettää tämän bearer tokenin API-käyttäjälle JSON-muodossa.

Kun API-käyttäjä on saanut bearer tokenin, kaikki seuraavat Spotnanan API-kutsut (esim. Trip API:t]) tulee tehdä siten, että bearer token on mukana otsikossa tunnistautumista varten.

Huom: API-päätepisteellä get-auth-token(clientId, clientSecret) on rajoitus: korkeintaan 100 kutsua 5 minuutissa.

iFrame-pohjainen tunnistautuminen

iFrame- eli upotettu ratkaisu tarkoittaa, että kumppani upottaa Spotnanan käyttöliittymän omaan käyttöliittymäänsä, jolloin käyttäjät käyttävät Spotnanaa kumppanin käyttöliittymän kautta. Tässä mallissa käyttäjän tunnistautuminen perustuu tokenien vaihtoon Spotnanan ja kumppanin järjestelmien välillä.

Huom: iFrame-pohjaisessa tunnistautumisessa käyttäjästä käytetään nimitystä caller. Tämä mahdollistaa tilanteet, joissa API- tai konekäyttäjä kirjautuu ja pyytää käyttöoikeustunnusta toisen käyttäjän puolesta. Tällainen käyttäjä voi käyttää esimerkiksi TMC-pääkäyttäjän tunnuksia yhdistyäkseen suoraan Spotnanan palvelimeen. Tästä syystä käytämme caller -termiä yleisnimityksenä käyttäjälle, joka kirjautuu omaan profiiliinsa tai API/konekäyttäjälle, joka pyytää käyttöoikeustunnusta toisen käyttäjän puolesta.

Alla oleva sekvenssikaavio näyttää, miten tunnistautuminen etenee tokenien vaihdon avulla Spotnanan ja kumppanin palvelimien välillä.

Kuva: Sekvenssikaavio, jossa kuvataan iFrame-pohjainen tunnistautuminen token-vaihdolla.

Vaihe	Kulku
Caller kirjautuu sisään kumppanin käyttöliittymän kautta.
1	Kumppanin käyttöliittymä näyttää Spotnanan käyttöliittymän iFramen kautta.
2	Spotnanan käyttöliittymä lähettää post message -viestin kumppanin käyttöliittymälle tokenien hakemiseksi. Pyynnössä on mukana `type=TOKEN_EXCHANGE_REQUEST`.
3	Kumppanin käyttöliittymä lähettää API-pyynnön kumppanin palvelimelle OAuth-tunnuksen hakemiseksi, mikä käynnistää seuraavat vaiheet tunnistautumisprosessissa.
3 a	Kumppanin palvelin kutsuu Spotnanan palvelinta käyttäjän tunnistetiedoilla ja subject tokenilla. Spotnanan palvelin tarkistaa, onko pyyntö tullut API- tai konekäyttäjältä.
3 b	Spotnanan palvelin kutsuu kumppanin palvelinta hakeakseen subjectin (eli callerin) sähköpostiosoitteen. Sähköpostiosoite haetaan ja palautetaan Spotnanan palvelimelle, joka tunnistaa käyttäjän sen avulla.
3 c	Spotnanan palvelin palauttaa vaiheessa 1 tehtyyn API-pyyntöön vastauksena access tokenin ja refresh tokenin kumppanin palvelimelle. Nämä tiedot välitetään edelleen kumppanin käyttöliittymään.
4	Kumppanin käyttöliittymä lähettää tokenin Spotnanan käyttöliittymälle post message -viestillä, jossa on `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnanan käyttöliittymä lähettää API-pyynnön Spotnanan palvelimelle uuden bearer tokenin luomiseksi ja hakemiseksi. Spotnanan palvelin luo bearer tokenin ja palauttaa sen Spotnanan käyttöliittymälle. Huom: Bearer tokenin onnistunut luonti tarkoittaa, että käyttäjä on tunnistettu ja saa käyttää Spotnanaa.
6	Kun käyttäjä on tunnistettu vaiheessa 3, kaikki seuraavat API-pyynnöt tulee lähettää siten, että otsikossa on bearer token sekä `orgId`ja `tmcId` . Kaikissa tulevissa API-pyynnöissä bearer token tarkistetaan ja vastaus palautetaan Spotnanan käyttöliittymään.

Auth code -pohjainen tunnistautuminen

Alla oleva sekvenssikaavio näyttää, miten tunnistautuminen etenee käyttämällä valtuutuskoodia.

Kuva: Sekvenssikaavio, jossa kuvataan auth code -pohjainen tunnistautuminen.

Vaihe	Kulku
1	Kumppanin käyttöliittymä pyytää kumppanin palvelimelta auth code -koodin callerille, joka kirjautuu sisään. Auth code palautetaan kumppanin käyttöliittymälle.
2	Kumppanin käyttöliittymä lähettää pyynnön Spotnanan käyttöliittymälle käyttäen räätälöityä uudelleenohjausosoitetta, jossa on mukana `tmcId` ja `authCode` parametreina.
3	Spotnanan käyttöliittymä tekee POST API-kutsun Spotnanan palvelimelle käyttäen `v2/auth/token/companies/<tmcId>(authCode)` API-päätepistettä.
3 a	Spotnanan palvelin lähettää pyynnön kumppanin palvelimelle hakeakseen käyttäjän `pid` auth code -koodin avulla. Käyttäjän `pid` haetaan ja lähetetään Spotnanan palvelimelle.
3 b	Spotnanan palvelin luo access tokenin ja refresh tokenin ja lähettää ne Spotnanan käyttöliittymälle.
4	Spotnanan käyttöliittymä lähettää pyynnön Spotnanan palvelimelle käyttäen access tokenia ja refresh tokenia saadakseen bearer tokenin pääsyä varten. Bearer token luodaan ja lähetetään Spotnanan käyttöliittymälle. Huom: Bearer tokenin onnistunut luonti tarkoittaa, että käyttäjä on tunnistettu ja saa käyttää Spotnanaa.
5	Kun käyttäjä on tunnistettu vaiheessa 4, kaikki seuraavat API-pyynnöt tulee lähettää siten, että otsikossa on bearer token sekä `orgId`ja `tmcId` . Kaikissa tulevissa API-pyynnöissä bearer token tarkistetaan ja vastaus palautetaan Spotnanan käyttöliittymään.

Huom: Tätä tunnistautumisprosessia ei voi käyttää, jos TMC-pääkäyttäjä sallii useamman käyttäjän kirjautua samalla sähköpostiosoitteella.

Koneiden välinen (M2M) tunnistautuminen

M2M-tunnistautuminen sopii tilanteisiin, joissa asiakassovellus käyttää kolmannen osapuolen callback-osoitetta accessTokenin luomiseen käyttäjälle. Alla oleva sekvenssikaavio kuvaa M2M-tunnistautumisen kulun. accessToken .

Kuva: Sekvenssikaavio, jossa kuvataan M2M-tunnistautumisen kulku.

Vaihe	Kulku
Kaikkien tunnistautumisessa käytettävien sovellusten julkiset avaimet synkronoidaan Spotnanan palvelimen ja Spotnanan IdP:n välillä. Näitä käytetään myöhemmin access tokenin tarkistamiseen tunnistautumisprosessissa.
1	Kumppanin palvelin lähettää API-pyynnön osoitteeseen `/oauth2/token(clientId,clientSecret)` Spotnanan IdP:ssä luodakseen bearer tokenin. Uusi bearer token palautetaan kumppanin palvelimelle.
2	Kumppanin palvelin lähettää API-pyynnön kolmannen osapuolen callback-osoitteeseen luodakseen käyttäjälle access tokenin. Tämä access token luodaan ja lähetetään Spotnanan palvelimelle.
3	Spotnanan palvelin tarkistaa access tokenin allekirjoituksen aiemmin synkronoitujen julkisten avainten avulla. Lisäksi tarkistetaan `claim_id` jolla varmistetaan kumppanin henkilöllisyys. Tämän jälkeen access token lähetetään kumppanin palvelimelle käyttäjän tunnistamiseksi.