Yfirlit yfir auðkenningarferli Spotnana

Búið til af Ashish Chaudhary, Breytt Sun, 5 Okt kl 10:32 AM eftir Ashish Chaudhary

Yfirlit yfir auðkenningarferla Spotnana

EFNISSKRÁ

Yfirlit yfir auðkenningarferla Spotnana
- Meginþættir
- Auðkenningaraðferðir sem eru studdar

Spotnana býður upp á ýmsar leiðir til auðkenningar sem gera samstarfsaðilum kleift að tryggja örugga tengingu við kerfið okkar. Hér er yfirlit yfir þær aðferðir sem Spotnana styður, ásamt nánari lýsingu á ferlunum. Þessir auðkenningarferlar sýna hvernig Spotnana sannreynir og veitir notendum aðgang að vernduðum auðlindum fyrirtækisins (þ.e. þeim gögnum sem fyrirtæki notandans á í Spotnana kerfinu).

Meginþættir

Áður en þú byrjar er gott að kynna sér helstu hugtök og kerfishluta sem vísað er til í þessari handbók.

Spotnana notendaviðmót(Spotnana User Interface) Þetta er vefviðmót Spotnana (þ.e. bókunarvefurinn) eða farsímaforritið. Hér er sérstaklega átt við innskráningarsíðuna, sem ræsir auðkenningarferlið þegar notandi skráir sig inn eða stofnar aðgang.
Spotnana þjónn Þetta er bakendaþjónn Spotnana sem sér um auðkenningu, veitir aðgang að gögnum og tryggir örugga meðhöndlun notendaupplýsinga.
Viðmót samstarfsaðila (Partner's User Interface) Þetta er það viðmót sem samstarfsaðilar nota til að tengjast Spotnana. Til dæmis, þegar Spotnana er fellt inn með iFrame, þá nota notendur Spotnana í gegnum viðmót samstarfsaðilans.
Þjónn samstarfsaðila Þetta eru bakendaþjónar samstarfsaðila sem tengja kerfi sín við Spotnana.
Spotnana auðkennisveita (IdP) (Spotnana Identity Provider) Þetta er innri þjónusta Spotnana sem sér um auðkenningu notenda og úthlutun heimilda.
Auðkennisveita samstarfsaðila Þriðju aðila auðkennisveitur sem samstarfsaðilar nota, til dæmis Google eða Azure.
OBT Rafbókunarvél Spotnana (OBT), aðgengileg á https://app.spotnana.com/
Notendamerki (subject token) Í iFrame-aðkenningu (eða auðkenningarskiptum) táknar notendamerkið auðkenni notandans. Það er notað til að sækja upplýsingar og veita aðgang að Spotnana.
Aðgangslykill (access token) Þetta er tímabundið auðkenningarskírteini (OAuth) sem samstarfsaðilar nota til að sækja vernduð gögn fyrir hönd notanda. Þannig þarf ekki að senda lykilorð notanda með hverri beiðni.
Endurnýjunarlykill (refresh token) Þetta er langtímalykill sem hægt er að nota til að fá nýjan aðgangslykil án þess að notandi þurfi að auðkenna sig aftur. Hann er venjulega gefinn út við fyrstu innskráningu.
Vottorð viðskiptavinar (client credentials) Þessar upplýsingar eru veittar þeim sem tengja sig beint við Spotnana API, þ.e.a.s. einstakt clientId og clientSecret).
Persónuauðkenni (PID) Persónuauðkenni sem er búið til fyrir hvern notanda og notað til að sækja upplýsingar hans úr Spotnana þjóninum.
orgId Einstakt auðkenni sem Spotnana úthlutar fyrir fyrirtæki notandans.
tmcId Einstakt auðkenni sem Spotnana úthlutar fyrir ferðaþjónustufyrirtæki (TMC).

Auðkenningaraðferðir sem eru studdar

Eftirfarandi eru þær auðkenningaraðferðir sem Spotnana styður:

Lykilorðaaðkenning
- Fyrirliggjandi notandi
- Nýr notandi
Auðkenning með auðkennisveitu (IdP)
Auðkenning með vefþjónustuviðmóti (API)
Auðkenning með innfelldum ramma (iFrame)
Auðkenning með auðkenningarkóða
Vél-til-vélar (M2M) auðkenning

Lykilorðaaðkenning

Þegar notað er lykilorðaaðkenningu, sér Spotnana notendaviðmótið (innskráningar- eða nýskráningarsíða í OBT) um að hefja og stjórna auðkenningarferlinu við Spotnana bakendaþjóna. Ferlið getur verið með tvenns konar flæði, eftir því hvort notandi skráir sig inn með fyrirliggjandi aðgang eða stofnar nýjan aðgang. Hér fyrir neðan eru báðir þessir ferlar útskýrðir með skýringarmyndum.

Fyrirliggjandi notandi

Skýringarmyndin og skrefin hér að neðan sýna hvernig Spotnana notendaviðmótið vinnur með bakendaþjónustum til að auðkenna notanda sem þegar á aðgang.

Mynd: Skýringarmynd sem sýnir lykilorðaaðkenningu fyrir fyrirliggjandi notendur.

Skref	Flæði
Fyrirliggjandi notandi skráir sig inn í gegnum OBT eða Spotnana farsímaforritið með netfangi sínu.
1	Spotnana notendaviðmótið sendir API-beiðni til Spotnana þjónsins til að sækja auðkenningarstillingar fyrir notandann. Í beiðninni eru innskráningarupplýsingar notandans. Svörun inniheldur `tmcId`, `orgId`og `authProviderType`.
2	Spotnana notendaviðmótið sendir API-beiðni til Spotnana auðkennisveitu með `clientId`, netfang og lykilorð. Spotnana auðkennisveitan býr til nýtt auðkenningartákn (bearer token) og sendir það til notendaviðmótsins. Þetta skref sannreynir notandann.
3	Eftir að notandi hefur verið sannreyndur í skrefi 2 þurfa allar næstu API-beiðnir að innihalda auðkenningartáknið, `orgId`og `tmcId` í haus beiðninnar. Auðkenningartáknið er sannreynt í öllum innkomandi API-beiðnum og svar sent til Spotnana notendaviðmótsins.

Nýr notandi

Skýringarmyndin og skrefin hér að neðan sýna hvernig Spotnana notendaviðmótið vinnur með bakendaþjónustum til að auðkenna nýjan notanda (eða notanda sem er að endurstilla lykilorð sitt).

Mynd: Skýringarmynd sem sýnir lykilorðaaðkenningu fyrir nýja notendur.

Skref	Flæði
Nýr notandi slær inn netfang sitt á innskráningarsíðu OBT og smellir á Áfram.
1	Spotnana notendaviðmótið sendir API-beiðni til Spotnana þjónsins til að sækja auðkenningarstillingar fyrir notandann. Í beiðninni eru innskráningarupplýsingar notandans. Svörun inniheldur `tmcId`, `orgId`og `authProviderType`.
1 a	Notandinn velur sér lykilorð og smellir á Áfram.
2	Spotnana notendaviðmótið sendir API-beiðni til Spotnana auðkennisveitu til að skrá notandann ásamt `clientId`, netfangi og nýju lykilorði. Eftir að upplýsingarnar hafa verið skráðar er einnota staðfestingarkóði (OTP) sendur í tölvupóst notandans.
3	Notandinn slær inn staðfestingarkóðann í Spotnana notendaviðmótið og smellir á Staðfesta. Spotnana notendaviðmótið sendir beiðni til Spotnana auðkennisveitu um að staðfesta OTP og búa til auðkenningartákn fyrir innskráningu. Auðkenningartáknið er búið til og sent til Spotnana notendaviðmótsins. Þetta þýðir að notandinn hefur verið auðkenndur og getur nú notað Spotnana með auðkenningartákninu.
4	Eftir að notandi hefur verið sannreyndur í skrefi 3 þurfa allar næstu API-beiðnir að innihalda auðkenningartáknið, `orgId`og `tmcId` í haus beiðninnar. Auðkenningartáknið er sannreynt í öllum innkomandi API-beiðnum og svar sent til Spotnana notendaviðmótsins.

Auðkenning með auðkennisveitu (IdP)

Spotnana styður auðkenningu í gegnum auðkennisveitur eins og Google, Azure og sérsniðnar lausnir með OpenID Connect eða SAML. Hér að neðan má sjá hvernig slíkt ferli gengur fyrir sig.

Mynd: Skýringarmynd sem sýnir auðkenningarferli með auðkennisveitu.

Skref	Flæði
Notandi skráir sig inn í gegnum OBT eða Spotnana farsímaforritið með netfangi sínu.
1	Spotnana notendaviðmótið sendir API-beiðni til Spotnana þjónsins til að sækja auðkenningarstillingar fyrir notandann. Í beiðninni eru innskráningarupplýsingar notandans. Svörun inniheldur `tmcId`, `orgId`og `authProviderType`.
2	Spotnana notendaviðmótið áframsendir beiðnina til Spotnana auðkennisveitu.
3	Spotnana auðkennisveitan áframsendir beiðnina til auðkennisveitu samstarfsaðila og auðkenningarferlið hefst þar. Athugið: Fyrir hverja áframsendingu er 302 stöðukóði sendur til að gefa til kynna að beiðnin hafi verið vísað á nýtt vefslóð.
4	Tenging er sett upp milli Spotnana auðkennisveitu og auðkennisveitu samstarfsaðila til að tryggja að notandinn sé sannreyndur þar. Athugið: Við þessa tengingu sendir Spotnana auðkennisveitan `clientId` og `clientSecret` sem formgögn (URL-encoded) í API-kalli til auðkennisveitu samstarfsaðila. Ef auðkennisþjónninn getur ekki unnið úr þessu formi getur Spotnana þjónninn starfað sem milliliður og breytt gögnunum í viðeigandi form.
5	Auðkennisveita samstarfsaðila sannreynir notandann. Athugið: Eftir þetta þarf notandinn samt að fara í gegnum sannvottun með auðkenningartákni.
5 a	Eftir að notandi hefur verið sannreyndur sendir auðkennisveita samstarfsaðila svar til Spotnana auðkennisveitu.
5 b	Spotnana auðkennisveitan býr til einkvæman kóða fyrir notandann og sendir hann til Spotnana notendaviðmótsins.
6	Spotnana notendaviðmótið sendir API-beiðni til Spotnana auðkennisveitu með `clientID` og kóðann sem fékkst í skrefi 5(b). Spotnana auðkennisveitan býr til nýtt auðkenningartákn og sendir það til notendaviðmótsins. Athugið: Þegar auðkenningartákn hefur verið búið til er notandinn sannreyndur og fær aðgang að Spotnana.
7	Eftir að notandi hefur verið sannreyndur í skrefi 6 þurfa allar næstu API-beiðnir að innihalda auðkenningartáknið, `orgId`og `tmcId` í haus beiðninnar. Auðkenningartáknið er sannreynt í öllum innkomandi API-beiðnum og svar sent til Spotnana notendaviðmótsins.

Auðkenning með vefþjónustuviðmóti (API)

Samstarfsaðilar sem nýta Spotnana API geta notað auðkenningarenda til að búa til auðkenningartákn fyrir sína notendur. Hér er skýringarmynd sem sýnir hvernig þetta ferli gengur fyrir sig.

Mynd: Skýringarmynd sem sýnir auðkenningu með vefþjónustuviðmóti (API).

Skref Flæði

Skref	Flæði
1	API-notandi framkvæmir POST kall á `get-auth-token(clientId,clientSecret)` API-endapunkt Spotnana þjónsins til að búa til og sækja tímabundið auðkenningartákn. Dæmi um cUrl-beiðni til að nota við `get-auth-token` endpoint: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Athugið: Settu inn þau `clientId` og `clientSecret` gildi sem þú hefur fengið frá Spotnana.
2	Spotnana þjónninn kallar á `getToken(clientId,clientSecret)` aðferðina í Spotnana auðkennisveitu, sem býr til tímabundið `bearerToken` og sendir það aftur til Spotnana þjónsins. Spotnana þjónninn sendir þetta auðkenningartákn til API-notandans sem JSON svar.

API-notandi framkvæmir POST kall á get-auth-token(clientId,clientSecret) API-endapunkt Spotnana þjónsins til að búa til og sækja tímabundið auðkenningartákn.

Dæmi um cUrl-beiðni til að nota við get-auth-token endpoint:

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

Athugið: Settu inn þau clientId og clientSecret gildi sem þú hefur fengið frá Spotnana.

Spotnana þjónninn kallar á getToken(clientId,clientSecret) aðferðina í Spotnana auðkennisveitu, sem býr til tímabundið bearerToken og sendir það aftur til Spotnana þjónsins.
Spotnana þjónninn sendir þetta auðkenningartákn til API-notandans sem JSON svar.

Eftir að API-notandinn hefur fengið auðkenningartáknið þarf að senda það með öllum frekari beiðnum til Spotnana API (t.d. ferðabeiðnir) í hausnum til auðkenningar.

Athugið: Endapunkturinn get-auth-token(clientId, clientSecret) hefur takmörkun á 100 API-köll á hverjar 5 mínútur.

Auðkenning með innfelldum ramma (iFrame)

Ef samstarfsaðilar fella Spotnana notendaviðmótið inn í sitt eigið viðmót (iFrame), þá fara notendur inn í Spotnana í gegnum samstarfsaðilann. Í þessu tilviki fer auðkenningin fram með táknaskiptum milli kerfa samstarfsaðila og Spotnana.

Athugið: Í iFrame-aðkenningu er notandinn sem skráir sig inn kallaður innskráningaraðili (caller). Þetta er gert til að taka mið af tilvikum þar sem API/vélanotandi skráir sig inn og sækir aðgangslykil fyrir annan notanda. Slíkur notandi gæti verið TMC-stjórnandi sem tengist beint við Spotnana þjóninn. Því notum við hugtakið innskráningaraðili (caller) sem samheiti yfir notanda sem skráir sig inn sjálfur eða vélanotanda sem sækir aðgang fyrir annan.

Skýringarmyndin hér að neðan sýnir hvernig auðkenningarferlið fer fram með táknaskiptum milli Spotnana og samstarfsaðila.

Mynd: Skýringarmynd sem sýnir iFrame-aðkenningu með táknaskiptum.

Skref	Flæði
Innskráningaraðili skráir sig inn í gegnum viðmót samstarfsaðila.
1	Viðmót samstarfsaðila birtir Spotnana notendaviðmótið í iFrame.
2	Spotnana notendaviðmótið sendir beiðni til viðmóts samstarfsaðila með post message til að sækja tákn. Beiðnin er merkt með `type=TOKEN_EXCHANGE_REQUEST`.
3	Viðmót samstarfsaðila sendir API-beiðni til samstarfsaðilaþjónsins til að sækja OAuth-tákn og hefja næstu skref í auðkenningarferlinu.
3 a	Samstarfsaðilaþjónninn kallar á Spotnana þjóninn með notendaupplýsingum og notendamerki (subject token) sem breytur. Spotnana þjónninn athugar hvort beiðnin kemur frá vélanotanda.
3 b	Spotnana þjónninn kallar á samstarfsaðilaþjóninn til að sækja netfang innskráningaraðila. Netfangið er sótt og sent til Spotnana þjónsins, sem notar það til að auðkenna notandann.
3 c	Svar við API-beiðni úr skrefi 1 er sent frá Spotnana þjóninum til samstarfsaðilaþjónsins með aðgangslykli og endurnýjunarlykli. Þessar upplýsingar eru síðan sendar áfram til viðmóts samstarfsaðila.
4	Viðmót samstarfsaðila sendir táknið til Spotnana notendaviðmótsins með post message merkt `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana notendaviðmótið sendir API-beiðni til Spotnana þjónsins til að búa til og sækja nýtt auðkenningartákn. Auðkenningartákn er búið til af Spotnana þjóninum og sent til notendaviðmótsins. Athugið: Þegar auðkenningartákn hefur verið búið til er notandinn sannreyndur og fær aðgang að Spotnana.
6	Eftir að notandi hefur verið sannreyndur í skrefi 3 þurfa allar næstu API-beiðnir að innihalda auðkenningartáknið, `orgId`og `tmcId` í haus beiðninnar. Auðkenningartáknið er sannreynt í öllum innkomandi API-beiðnum og svar sent til Spotnana notendaviðmótsins.

Auðkenning með auðkenningarkóða

Skýringarmyndin hér að neðan sýnir hvernig auðkenningarferlið fer fram þegar notaður er auðkenningarkóði.

Mynd: Skýringarmynd sem sýnir auðkenningu með auðkenningarkóða.

Skref	Flæði
1	Viðmót samstarfsaðila kallar á samstarfsaðilaþjóninn til að sækja auðkenningarkóða fyrir innskráningaraðila. Kóðinn er sóttur og sendur til viðmóts samstarfsaðila.
2	Viðmót samstarfsaðila sendir beiðni til Spotnana notendaviðmótsins með sérsniðinni áframsendingarslóð sem inniheldur `tmcId` og `authCode` sem breytur.
3	Spotnana notendaviðmótið framkvæmir POST API-kall til Spotnana þjónsins með `v2/auth/token/companies/<tmcId>(authCode)` API-endapunktinum.
3 a	Spotnana þjónninn sendir beiðni til samstarfsaðilaþjónsins til að sækja `pid` notandans með auth code. pid `notandans er sótt og sent til Spotnana þjónsins.` 3 b
Aðgangslykill og endurnýjunarlykill eru búnir til af Spotnana þjóninum og sendir til notendaviðmótsins.	4
Spotnana notendaviðmótið sendir beiðni til Spotnana þjónsins með aðgangslykli og endurnýjunarlykli til að búa til og sækja auðkenningartákn fyrir aðgang.	Auðkenningartákn er búið til og sent til Spotnana notendaviðmótsins. Athugið: Þegar auðkenningartákn hefur verið búið til er notandinn sannreyndur og fær aðgang að Spotnana. 5
Eftir að notandi hefur verið sannreyndur í skrefi 4 þurfa allar næstu API-beiðnir að innihalda auðkenningartáknið,	orgId `og`tmcId `í haus beiðninnar.` Auðkenningartáknið er sannreynt í öllum innkomandi API-beiðnum og svar sent til Spotnana notendaviðmótsins. Athugið:

Þetta auðkenningarflæði hentar ekki ef TMC-stjórnandi leyfir fleiri en einum notanda að nota sama netfang við innskráningu. Vél-til-vélar (M2M) auðkenning

M2M-aðkenning hentar þegar viðskiptavinaforrit þarf að sækja aðgangslykil fyrir notanda í gegnum utanaðkomandi slóð. Hér að neðan er skýringarmynd sem sýnir þetta ferli.

accessToken fyrir notandann. Skýringarmyndin sýnir hvernig þetta ferli gengur fyrir sig. Mynd:

Skýringarmynd sem sýnir vél-til-vélar auðkenningarferli. Skref

Flæði	Opinberir lyklar allra forrita sem taka þátt í auðkenningunni eru samstilltir milli Spotnana þjónsins og Spotnana auðkennisveitu. Þessir lyklar eru notaðir síðar til að sannreyna aðgangslykilinn.
1
Samstarfsaðilaþjónninn sendir API-beiðni á	/oauth2/token(clientId,clientSecret) `í Spotnana auðkennisveitu til að búa til auðkenningartákn. Nýtt auðkenningartákn er sent til samstarfsaðilaþjónsins.` 2
Samstarfsaðilaþjónninn sendir API-beiðni á utanaðkomandi slóð til að búa til aðgangslykil fyrir notandann.	Aðgangslykillinn er búinn til og sendur til Spotnana þjónsins. 3
Spotnana þjónninn sannreynir undirritun aðgangslykilsins með opinberum lyklum sem voru samstilltir áður. Hann sannreynir einnig	claim_id `sem staðfestir auðkenni samstarfsaðilans.` Aðgangslykillinn er svo sendur til samstarfsaðilaþjónsins til að auðkenna notandann. ...