Pangkalahatang-ideya ng mga paraan ng pag-aawtentika sa Spotnana

Ginawa ni Ashish Chaudhary, Binago sa Sun, 5 Oktubre sa 5:02 AM ni Ashish Chaudhary

Pangkalahatang-ideya ng mga daloy ng pagpapatunay sa Spotnana

TALAAN NG NILALAMAN

Pangkalahatang-ideya ng mga daloy ng pagpapatunay sa Spotnana
- Mahalagang mga bahagi
- Mga suportadong paraan ng pagpapatunay

Nag-aalok ang Spotnana ng iba’t ibang paraan ng pagpapatunay upang matiyak ang ligtas na integrasyon ng mga katuwang sa aming plataporma. Sa dokumentasyong ito, tatalakayin ang mga paraan ng pagpapatunay na kasalukuyang sinusuportahan ng Spotnana, pati na rin ang detalyadong paliwanag ng bawat proseso. Ipinapakita ng mga daloy ng pagpapatunay dito kung paano pinapatunayan at binibigyang-pahintulot ng Spotnana ang mga gumagamit upang makapasok sa mga protektadong mapagkukunan ng kanilang organisasyon (ibig sabihin, mga mapagkukunang pag-aari ng kumpanya ng gumagamit sa Spotnana platform).

Mahalagang mga bahagi

Bago ka magsimula, suriin muna ang talaang ito para sa mga kahulugan ng mahahalagang bahagi ng sistema na binabanggit sa dokumentasyong ito.

Spotnana UI(Spotnana User Interface) Tumutukoy ito sa harapang web application ng Spotnana (Online Booking Tool) o mobile application ng Spotnana. Partikular, ito ang login page na nagsisimula ng proseso ng pagpapatunay tuwing magla-login o gagawa ng bagong account ang gumagamit.
Spotnana server Tumutukoy ito sa backend server ng Spotnana na ginagamit para sa pagpapatunay (halimbawa, pagbibigay-pahintulot sa gumagamit na makapasok sa mapagkukunan at ligtas na pagtatago at pagproseso ng impormasyon ng gumagamit).
Partner UI (User Interface ng Katuwang) Ang user interface (ibig sabihin, frontend application) na ginagamit ng mga katuwang upang makapasok sa Spotnana platform. Halimbawa, sa pagpapatunay gamit ang iFrame, naka-embed ang Spotnana platform sa UI ng katuwang at dito dadaan ang mga gumagamit upang makapasok sa Spotnana.
Partner server Tumutukoy ito sa isa o higit pang backend server na ginagamit ng aming mga katuwang para mag-integrate sa Spotnana.
Spotnana IdP (Spotnana Identity Provider) Tumutukoy ito sa panloob na serbisyo ng Spotnana para sa pamamahala ng pagkakakilanlan at awtorisasyon ng mga gumagamit.
Partner IdP Ikatlong-partidong Identity Provider (IdP) na ginagamit ng mga katuwang. Ilan sa mga karaniwang IdP ay ang Google at Azure.
OBT Online Booking Tool (OBT) ng Spotnana, na maaaring ma-access sa https://app.spotnana.com/
Subject token Sa pagpapatunay gamit ang iFrame (o token exchange), ang subject token ay kumakatawan sa pagkakakilanlan ng gumagamit. Ginagamit ang token na ito upang kunin ang impormasyon ng gumagamit at bigyan siya ng pahintulot na makapasok sa Spotnana platform.
Access token Isang kredensyal (OAuth) na ginagamit ng partner application upang makapasok sa mga protektadong mapagkukunan para sa isang gumagamit. Pansamantalang susi ito ng awtorisasyon na nagpapahintulot sa mga application na magpadala ng API request nang hindi nilalantad ang mismong kredensyal ng gumagamit.
Refresh token Isang pangmatagalang kredensyal na ginagamit upang makakuha ng panibagong access token nang hindi na kailangang mag-login muli ang gumagamit. Karaniwan itong ibinibigay kasabay ng access token kapag unang nag-login ang gumagamit.
Client credentials Ang impormasyon na ibinibigay sa mga gumagamit na direktang kumokonekta sa Spotnana APIs (halimbawa, isang natatanging clientId at clientSecret).
PID (Personal identifier) Isang personal na tagatukoy na nilikha para sa gumagamit. Sa pamamagitan ng PID, kinukuha ang impormasyon ng gumagamit mula sa Spotnana server.
orgId Isang natatanging tagatukoy na ibinibigay ng Spotnana para sa organisasyon ng gumagamit.
tmcId Isang natatanging tagatukoy na ibinibigay ng Spotnana para sa isang TMC (Travel Management Company).

Mga suportadong paraan ng pagpapatunay

Narito ang iba’t ibang paraan ng pagpapatunay na sinusuportahan ng Spotnana:

Pagpapatunay gamit ang password
- Umiiral na gumagamit
- Bagong gumagamit
Pagpapatunay gamit ang IdP
Pagpapatunay gamit ang API
Pagpapatunay gamit ang iFrame
Pagpapatunay gamit ang auth code
Pagpapatunay ng makina-sa-makina (M2M)

Pagpapatunay gamit ang password

Kapag password ang gamit sa pagpapatunay, ang Spotnana UI (login o signup page sa OBT) ang nagsisimula at namamahala ng proseso ng pagpapatunay kasama ang backend server ng Spotnana. May dalawang posibleng daloy depende kung ang gumagamit ay magla-login gamit ang umiiral na profile o gagawa ng bagong account. Ipinaliwanag ang bawat daloy sa mga sumusunod na seksyon gamit ang sequence diagram.

Umiiral na gumagamit

Ang sequence diagram at mga hakbang sa ibaba ay nagpapaliwanag kung paano nakikipag-ugnayan ang Spotnana UI sa backend services upang mapatunayan ang umiiral na gumagamit.

Larawan: Isang sequence diagram na nagpapakita ng proseso ng pagpapatunay gamit ang password para sa umiiral na mga gumagamit.

Hakbang	Daloy
Ang umiiral na gumagamit ay nagla-login sa OBT o sa Spotnana mobile application gamit ang kanilang email.
1	Magpapadala ang Spotnana UI ng API request sa Spotnana server upang kunin ang auth configuration ng gumagamit. Kasama sa request ang login credentials ng gumagamit bilang mga parameter. Ang tugon ay naglalaman ng `tmcId`, `orgId`, at `authProviderType`.
2	Magpapadala ang Spotnana UI ng API request sa Spotnana IdP gamit ang `clientId`, email, at password. Magge-generate ang Spotnana IdP ng bagong bearer token at ibabalik ito sa Spotnana UI. Sa hakbang na ito, napapatunayan ang gumagamit.
3	Kapag napapatunayan na ang gumagamit sa hakbang 2, lahat ng susunod na API request ay dapat may kasamang bearer token, `orgId`, at `tmcId` sa header ng request. Tinitiyak na valid ang bearer token sa lahat ng papasok na API request at ipapadala ang tugon pabalik sa Spotnana UI.

Bagong gumagamit

Ang sequence diagram at mga hakbang sa ibaba ay nagpapaliwanag kung paano pinapatunayan ng Spotnana UI ang bagong gumagamit (o umiiral na gumagamit na nagre-reset ng password) sa pamamagitan ng backend services.

Larawan: Isang sequence diagram na nagpapakita ng proseso ng pagpapatunay gamit ang password para sa mga bagong gumagamit.

Hakbang	Daloy
Ang bagong gumagamit ay ilalagay ang kanilang email sa Spotnana OBT login page at pipindutin ang Next.
1	Magpapadala ang Spotnana UI ng API request sa Spotnana server upang kunin ang auth configuration ng gumagamit. Kasama sa request ang login credentials ng gumagamit bilang mga parameter. Ang tugon ay naglalaman ng `tmcId`, `orgId`, at `authProviderType`.
1 a	Ilalagay ng gumagamit ang bagong password at pipindutin ang Next.
2	Magpapadala ang Spotnana UI ng API request sa Spotnana IdP upang irehistro ang gumagamit kasama ang kanilang `clientId`, email, at bagong password. Pagkatapos maitala ang mga detalye, magpapadala ng One-Time Password (OTP) sa email ng gumagamit.
3	Ilalagay ng gumagamit ang OTP sa Spotnana UI at pipindutin ang Verify. Magpapadala ang Spotnana UI ng request sa Spotnana IdP upang beripikahin ang OTP at mag-generate ng bearer token para sa login. Kapag nagawa na ang bearer token at naibalik sa Spotnana UI, nangangahulugan ito na matagumpay ang pagpapatunay at maaari nang gamitin ng gumagamit ang Spotnana platform gamit ang bearer token.
4	Kapag napapatunayan na ang gumagamit sa hakbang 3, lahat ng susunod na API request ay dapat may kasamang bearer token, `orgId`, at `tmcId` sa header ng request. Tinitiyak na valid ang bearer token sa lahat ng papasok na API request at ipapadala ang tugon pabalik sa Spotnana UI.

Pagpapatunay gamit ang IdP

Sinusuportahan ng Spotnana ang pagpapatunay sa pamamagitan ng mga IdP tulad ng Google, Azure, at mga custom IdP gamit ang OpenID Connect at SAML protocol. Ang sequence diagram at mga hakbang sa ibaba ay nagpapaliwanag ng daloy ng pagpapatunay gamit ang IdP.

Larawan: Isang sequence diagram na nagpapakita ng daloy ng pagpapatunay gamit ang IdP.

Hakbang	Daloy
Nagla-login ang gumagamit sa OBT o Spotnana mobile application gamit ang kanilang email.
1	Magpapadala ang Spotnana UI ng API request sa Spotnana server upang kunin ang auth configuration ng gumagamit. Kasama sa request ang login credentials ng gumagamit bilang mga parameter. Ang tugon ay naglalaman ng `tmcId`, `orgId`, at `authProviderType`.
2	Ire-redirect ng Spotnana UI ang request papunta sa Spotnana IdP.
3	Ire-redirect ng Spotnana IdP ang request papunta sa IdP ng katuwang. Dito magsisimula ang pagpapatunay ng IdP para sa gumagamit. Tandaan: Sa bawat redirect, ang status code na 302 ay ibinabalik bilang palatandaan na nailipat ang request sa ibang URL.
4	Nagkakaroon ng koneksyon sa pagitan ng Spotnana IdP at ng IdP ng katuwang upang matiyak na mapapatunayan ang gumagamit ng partner IdP. Tandaan: Sa koneksyong ito, ipinapadala ng Spotnana IdP ang `clientId` at `clientSecret` bilang form URL-encoded data gamit ang API call sa Partner IdP. Kung hindi kayang iproseso ng IdP server ang format na ito, maaaring magsilbing proxy ang Spotnana server upang i-convert ito sa format na tinatanggap ng partner IdP.
5	Matagumpay na napapatunayan ng partner IdP ang gumagamit. Tandaan: Pagkatapos nito, kailangang dumaan pa rin ang profile ng gumagamit sa beripikasyon ng bearer token.
5 a	Pagkatapos ng matagumpay na pagpapatunay, ipapadala ng partner IdP ang tugon sa Spotnana IdP.
5 b	Gumagawa ang Spotnana IdP ng natatanging code para sa profile ng gumagamit at ipinapadala ito sa Spotnana UI.
6	Magpapadala ang Spotnana UI ng API request sa Spotnana IdP gamit ang `clientID` at ang code na natanggap sa hakbang 5(b). Magge-generate ang Spotnana IdP ng bagong bearer token at ipapadala ito sa Spotnana UI. Tandaan: Ang matagumpay na paglikha ng bearer token ay nangangahulugang napapatunayan na ang gumagamit at maaari nang makapasok sa Spotnana.
7	Kapag napapatunayan na ang gumagamit sa hakbang 6, lahat ng susunod na API request ay dapat may kasamang bearer token, `orgId`, at `tmcId` sa header ng request. Tinitiyak na valid ang bearer token sa lahat ng papasok na API request at ipapadala ang tugon pabalik sa Spotnana UI.

Pagpapatunay gamit ang API

Para sa mga katuwang na gumagamit ng Spotnana APIs upang kumonekta sa Spotnana platform, maaari nilang gamitin ang aming authentication endpoint upang makabuo ng bearer token para sa kanilang mga gumagamit. Ang sumusunod na sequence diagram ay nagpapakita ng daloy ng pagpapatunay para sa mga katuwang na gumagamit ng API-based authentication.

Larawan: Isang sequence diagram na nagpapaliwanag ng pagpapatunay gamit ang API.

Hakbang Daloy

Hakbang	Daloy
1	Ang API user ay gagawa ng POST request sa `get-auth-token(clientId,clientSecret)` API endpoint sa Spotnana server upang makabuo at makuha ang pansamantalang bearer token. Narito ang halimbawa ng cUrl request na maaaring gamitin sa pagtawag sa `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>" }' Tandaan: Palitan ang `clientId` at `clientSecret` ng mga kredensyal na ibinigay sa inyo ng Spotnana.
2	Tatawag ang Spotnana server sa `getToken(clientId,clientSecret)` method sa Spotnana IdP upang makabuo ng pansamantalang `bearerToken` at ibabalik ito sa Spotnana server. Ipadadala ng Spotnana server ang bearer token na ito bilang JSON response sa API user.

Ang API user ay gagawa ng POST request sa get-auth-token(clientId,clientSecret) API endpoint sa Spotnana server upang makabuo at makuha ang pansamantalang bearer token.

Narito ang halimbawa ng cUrl request na maaaring gamitin sa pagtawag sa 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>"
}'

Tandaan: Palitan ang clientId at clientSecret ng mga kredensyal na ibinigay sa inyo ng Spotnana.

Tatawag ang Spotnana server sa getToken(clientId,clientSecret) method sa Spotnana IdP upang makabuo ng pansamantalang bearerToken at ibabalik ito sa Spotnana server.
Ipadadala ng Spotnana server ang bearer token na ito bilang JSON response sa API user.

Kapag natanggap na ng API user ang bearer token, lahat ng susunod na request sa Spotnana APIs (halimbawa, Trip APIs) ay kailangang may kasamang bearer token sa header bilang awtorisasyon.

Tandaan: Ang get-auth-token(clientId, clientSecret) endpoint ay may limitasyon na 100 API calls bawat 5 minuto.

Pagpapatunay gamit ang iFrame

Ang iFrame o embedded solution ay kapag ang Spotnana UI ay naka-embed sa UI ng katuwang, kaya’t ang mga gumagamit ay dumadaan sa partner UI upang makapasok sa Spotnana. Sa ganitong setup, ang pagpapatunay ng gumagamit ay nakabase sa palitan ng token sa pagitan ng sistema ng katuwang at Spotnana.

Tandaan: Para sa pagpapatunay gamit ang iFrame, ang gumagamit na nagla-login ay tatawagin bilang caller. Ginagawa ito upang matugunan ang mga sitwasyon kung saan ang isang API/Machine user ay nagla-login at humihingi ng access token para sa ibang gumagamit. Maaaring gumamit ng TMC (Travel Management Company) admin credentials ang API/Machine user upang direktang kumonekta sa Spotnana server. Kaya, gagamitin natin ang caller bilang pangkalahatang termino, maaaring tumukoy ito sa gumagamit na nagla-login sa sariling profile o API/Machine user na humihingi ng access token para sa iba.

Nasa ibaba ang sequence diagram na nagpapakita kung paano pinangangasiwaan ang pagpapatunay gamit ang token exchange sa pagitan ng Spotnana at partner servers.

Larawan: Isang sequence diagram na nagpapaliwanag ng pagpapatunay gamit ang iFrame at token exchange.

Hakbang	Daloy
Ang caller ay nagla-login gamit ang Partner UI.
1	Ire-render ng partner UI ang Spotnana UI sa pamamagitan ng iFrame.
2	Magpapadala ang Spotnana UI ng request sa partner UI gamit ang post message upang kunin ang mga token. Ang request ay may kasamang `type=TOKEN_EXCHANGE_REQUEST`.
3	Magpapadala ang Partner UI ng API request sa partner server upang kunin ang OAuth token, na magsisimula ng mga susunod na hakbang sa authentication flow.
3 a	Tatawag ang partner server sa Spotnana server gamit ang user credentials at subject token bilang mga parameter. Titingnan ng Spotnana server kung ang request ay mula sa API/Machine user.
3 b	Tatawag ang Spotnana server sa partner server upang kunin ang email ng subject (caller). Kukunin ang email at ibabalik sa Spotnana server, na gagamitin upang matukoy ang gumagamit.
3 c	Ang tugon sa API request mula sa hakbang 1 ay ipapadala ng Spotnana server sa partner server na naglalaman ng access token at refresh token. Ipadadala naman ang mga detalye sa Partner UI.
4	Ipadadala ng partner UI ang token sa Spotnana UI gamit ang post message na may `type=TOKEN_EXCHANGE_RESPONSE.`
5	Magpapadala ang Spotnana UI ng API request sa Spotnana server upang makabuo at makuha ang bagong bearer token. Magge-generate ang Spotnana server ng bearer token at ibabalik ito sa Spotnana UI. Tandaan: Ang matagumpay na paglikha ng bearer token ay nangangahulugang napapatunayan na ang gumagamit at maaari nang makapasok sa Spotnana.
6	Kapag napapatunayan na ang gumagamit sa hakbang 3, lahat ng susunod na API request ay dapat may kasamang bearer token, `orgId`, at `tmcId` sa header ng request. Tinitiyak na valid ang bearer token sa lahat ng papasok na API request at ipapadala ang tugon pabalik sa Spotnana UI.

Pagpapatunay gamit ang auth code

Nasa ibaba ang sequence diagram na nagpapakita kung paano pinangangasiwaan ang pagpapatunay gamit ang authorization code.

Larawan: Isang sequence diagram na nagpapaliwanag ng pagpapatunay gamit ang auth code.

Hakbang	Daloy
1	Tatawag ang partner UI sa partner server upang kunin ang auth code para sa caller na nagla-login. Makukuha ang auth code at ibabalik sa partner UI.
2	Magpapadala ang Partner UI ng request sa Spotnana UI gamit ang custom redirect URL na may `tmcId` at `authCode` bilang mga parameter.
3	Gagawa ang Spotnana UI ng POST API call sa Spotnana server gamit ang `v2/auth/token/companies/<tmcId>(authCode)` API endpoint.
3 a	Magpapadala ang Spotnana server ng request sa partner server upang kunin ang `pid` ng gumagamit gamit ang auth code. Makukuha ang `pid` ng gumagamit at ipapadala ito sa Spotnana server.
3 b	Gagawa ang Spotnana server ng access token at refresh token at ipapadala ito sa Spotnana UI.
4	Magpapadala ang Spotnana UI ng request sa Spotnana server gamit ang access token at refresh token upang makabuo at makuha ang bearer token para sa access. Gagawa at ipapadala ang bearer token sa Spotnana UI. Tandaan: Ang matagumpay na paglikha ng bearer token ay nangangahulugang napapatunayan na ang gumagamit at maaari nang makapasok sa Spotnana.
5	Kapag napapatunayan na ang gumagamit sa hakbang 4, lahat ng susunod na API request ay dapat may kasamang bearer token, `orgId`, at `tmcId` sa header ng request. Tinitiyak na valid ang bearer token sa lahat ng papasok na API request at ipapadala ang tugon pabalik sa Spotnana UI.

Tandaan: Hindi maaaring gamitin ang daloy na ito kung pinapayagan ng TMC admin na higit sa isang gumagamit ang gumamit ng iisang email sa pag-login.

Pagpapatunay ng makina-sa-makina (M2M)

Ang M2M authentication ay akma kung ang daloy ng pagpapatunay ay nangangailangan na ang client application ay kumonekta sa isang third-party callback URL upang makabuo ng accessToken para sa gumagamit. Ang sequence diagram sa ibaba ay nagpapakita ng M2M authentication flow.

Larawan: Isang sequence diagram na nagpapaliwanag ng daloy ng M2M authentication.

Hakbang	Daloy
Ang mga public key para sa lahat ng application na ginagamit sa pagpapatunay ay sinisigurong magkatugma sa pagitan ng Spotnana server at Spotnana IdP. Gagamitin ito upang beripikahin ang access token sa authentication flow.
1	Magpapadala ang partner server ng API request sa `/oauth2/token(clientId,clientSecret)` sa Spotnana IdP upang makabuo ng bearer token. Ipapadala ang bagong bearer token pabalik sa partner server.
2	Magpapadala ang partner server ng API request sa third-party callback URL upang makabuo ng access token para sa gumagamit. Gagawa ang access token at ipapadala ito sa Spotnana server.
3	Bine-verify ng Spotnana server ang lagda ng access token gamit ang mga public key na na-sync. Sini-sigurado rin ang `claim_id` upang mapatunayan ang pagkakakilanlan ng katuwang. Ipapadala ang access token sa partner server upang mapatunayan ang gumagamit.