Преглед процеса аутентификације у Spotnana систему

Креирао Ashish Chaudhary, Измењено на дан Sun, 5 Окт у 11:12 ПРЕ ПОДНЕ од стране Ashish Chaudhary

Преглед аутентификационих токова у Spotnana платформи

САДРЖАЈ

Преглед аутентификационих токова у Spotnana платформи
- Кључне компоненте
- Подржани начини аутентификације

Spotnana омогућава више начина аутентификације како би партнери могли безбедно да интегришу своје системе са нашом платформом. У овом документу ћете наћи преглед тренутно подржаних метода аутентификације, као и детаљна објашњења њихових токова. Ови аутентификациони токови показују како Spotnana идентификује и овлашћује кориснике за приступ заштићеним ресурсима на нивоу организације (односно ресурсима који припадају компанији корисника на Spotnana платформи).

Кључне компоненте

Пре него што започнете, погледајте ову листу са објашњењима основних компоненти система које се помињу у овом документу.

Spotnana кориснички интерфејс (UI)(Spotnana User Interface) Ово се односи на Spotnana веб апликацију (познату и као алат за онлајн резервације) или мобилну апликацију. Посебно се мисли на страницу за пријаву, која покреће процес аутентификације када се корисник пријављује или креира нови налог.
Spotnana сервер Означава Spotnana сервер на страни позадине, који се користи за аутентификацију (на пример, за овлашћивање приступа ресурсима и безбедно чување и обраду података о корисницима).
Кориснички интерфејс партнера (Partner UI) (Partner's User Interface) Интерфејс који користе партнери за приступ Spotnana платформи (то је њихова веб апликација). На пример, код аутентификације преко iFrame-а, Spotnana платформа се уграђује у партнерски интерфејс, па корисници приступају Spotnana-у преко Partner UI.
Сервер партнера Означава један или више серверa које наши партнери користе за интеграцију са Spotnana платформом.
Spotnana IdP (Spotnana Identity Provider) Ово је интерни Spotnana сервис који служи за управљање идентитетом корисника и њихово овлашћивање.
IdP партнера IdP (Identity Provider) треће стране који користе партнери. Најчешћи примери су Google и Azure.
OBT Spotnana алат за онлајн резервације (OBT), доступан на https://app.spotnana.com/
Subject token У iFrame или токен ексченџ аутентификацији, subject token представља идентитет корисника. Овај токен се користи за проналажење информација о кориснику и његово овлашћивање за приступ Spotnana платформи.
Access token Ово је привремени (OAuth) приступни кључ који партнерска апликација користи да би у име корисника приступила заштићеним ресурсима. Омогућава слање API захтева без излагања корисничких акредитива.
Refresh token Дугорочни приступни кључ који служи за добијање нових access token-а без поновне пријаве корисника. Обично се добија заједно са access token-ом приликом прве пријаве.
Client credentials Подаци који се додељују корисницима који директно приступају Spotnana API-јима (на пример, јединствени clientId и clientSecret).
PID (Лични идентификатор) Јединствени идентификатор који се додељује кориснику. PID служи за преузимање корисничких података са Spotnana сервера.
orgId Јединствени идентификатор који Spotnana додељује организацији корисника.
tmcId Јединствени идентификатор који Spotnana додељује TMC-у (компанији за управљање путовањима).

Подржани начини аутентификације

Spotnana тренутно подржава следеће начине аутентификације:

Аутентификација помоћу лозинке
- Постојећи корисник
- Нови корисник
Аутентификација преко IdP провајдера
Аутентификација путем API-ја
Аутентификација преко iFrame-а
Аутентификација помоћу ауторизационог кода
Аутентификација између машина (M2M)

Аутентификација помоћу лозинке

Када се користи аутентификација помоћу лозинке, Spotnana кориснички интерфејс (страница за пријаву или регистрацију у OBT-у) покреће и води цео процес аутентификације са Spotnana серверима. Овај процес може имати два различита тока у зависности од тога да ли се корисник пријављује са постојећим налогом или креира нови. Сваки од ова два тока је детаљно приказан у наставку, уз помоћ дијаграма секвенци.

Постојећи корисник

Дијаграм секвенце и кораци у наставку објашњавају како Spotnana UI комуницира са серверима у позадини ради аутентификације постојећег корисника.

Слика: Дијаграм секвенце који приказује процес аутентификације помоћу лозинке за постојеће кориснике.

Корак	Ток
Постојећи корисник се пријављује преко OBT-а или мобилне апликације Spotnana користећи своју имејл адресу.
1	Spotnana UI шаље API захтев Spotnana серверу да преузме информације о конфигурацији аутентификације за тог корисника. У захтеву се налазе кориснички подаци за пријаву. Одговор садржи корисникове `tmcId`, `orgId`и `authProviderType`.
2	Spotnana UI шаље API захтев Spotnana IdP-у са `clientId`, имејлом и лозинком. Spotnana IdP генерише нови bearer токен и враћа га Spotnana UI-ју. Овим кораком корисник је успешно аутентификован.
3	Када је корисник аутентификован у кораку 2, сви наредни API захтеви морају садржати bearer токен, `orgId`и `tmcId` у заглављу захтева. Bearer токен се проверава у сваком долазном API захтеву, а одговор се враћа Spotnana UI-ју.

Нови корисник

Дијаграм секвенце и кораци у наставку објашњавају како Spotnana UI комуницира са серверима ради аутентификације новог корисника (или постојећег корисника који ресетује лозинку).

Слика: Дијаграм секвенце који приказује процес аутентификације помоћу лозинке за нове кориснике.

Корак	Ток
Нови корисник уноси своју имејл адресу на страници за пријаву у Spotnana OBT-у и кликне на Next.
1	Spotnana UI шаље API захтев Spotnana серверу да преузме информације о конфигурацији аутентификације за тог корисника. У захтеву се налазе кориснички подаци за пријаву. Одговор садржи корисникове `tmcId`, `orgId`и `authProviderType`.
1 а	Корисник уноси нову лозинку и кликне на Next.
2	Spotnana UI шаље API захтев Spotnana IdP-у за регистрацију корисника, заједно са његовим `clientId`, имејлом и новом лозинком. Након што су подаци регистровани, на имејл корисника се шаље једнократна лозинка (OTP).
3	Корисник уноси OTP у Spotnana UI и кликне на Verify. Spotnana UI шаље захтев Spotnana IdP-у да верификује OTP и генерише bearer токен за пријаву. Bearer токен се генерише и враћа Spotnana UI-ју. Ово значи да је корисник успешно аутентификован и може приступити Spotnana платформи уз помоћ тог токена.
4	Када је корисник аутентификован у кораку 3, сви наредни API захтеви морају садржати bearer токен, `orgId`и `tmcId` у заглављу захтева. Bearer токен се проверава у сваком долазном API захтеву, а одговор се враћа Spotnana UI-ју.

Аутентификација преко IdP провајдера

Spotnana подржава аутентификацију преко IdP провајдера као што су Google, Azure и прилагођени IdP-ови који користе OpenID Connect или SAML протоколе. Дијаграм секвенце и кораци у наставку приказују ток аутентификације преко IdP-а.

Слика: Дијаграм секвенце који приказује ток аутентификације преко IdP-а.

Корак	Ток
Корисник се пријављује преко OBT-а или Spotnana мобилне апликације користећи своју имејл адресу.
1	Spotnana UI шаље API захтев Spotnana серверу да преузме податке о конфигурацији аутентификације за тог корисника. Захтев садржи корисничке акредитиве. Одговор садржи корисникове `tmcId`, `orgId`и `authProviderType`.
2	Spotnana UI преусмерава захтев ка Spotnana IdP-у.
3	Spotnana IdP преусмерава захтев ка IdP-у партнера. Овим почиње процес IdP аутентификације за корисника. Напомена: Сваки пут када дође до преусмеравања, враћа се статус код 302, што значи да је захтев преусмерен на другу адресу.
4	Успоставља се веза између Spotnana IdP-а и IdP-а партнера како би се проверила аутентичност корисника. Напомена: Током ове везе, Spotnana IdP шаље `clientId` и `clientSecret` као URL-енкодоване податке путем API позива ка IdP-у партнера. Ако сервер IdP-а не прихвата овај формат, Spotnana сервер може да делује као посредник и конвертује податке у формат који партнерски IdP препознаје.
5	IdP партнера успешно аутентификује корисника. Напомена: Након овог корака, профил корисника мора проћи и верификацију преко bearer токена.
5 а	По успешној аутентификацији, одговор од IdP-а партнера се шаље Spotnana IdP-у.
5 б	Spotnana IdP генерише јединствени код за кориснички профил и шаље га Spotnana UI-ју.
6	Spotnana UI шаље API захтев Spotnana IdP-у са `clientID` и кодом добијеним у кораку 5(б). Spotnana IdP генерише нови bearer токен и шаље га Spotnana UI-ју. Напомена: Успешно креирање bearer токена значи да је корисник аутентификован и може приступити Spotnana-у.
7	Када је корисник аутентификован у кораку 6, сви наредни API захтеви морају садржати bearer токен, `orgId`и `tmcId` у заглављу захтева. Bearer токен се проверава у сваком долазном API захтеву, а одговор се враћа Spotnana UI-ју.

Аутентификација путем API-ја

Партнери који користе Spotnana API-је за повезивање са платформом могу да користе наш аутентификациони крајњу тачку (endpoint) за генерисање bearer токена за своје кориснике. Следећи дијаграм секвенце приказује ток аутентификације за партнере који користе овај начин.

Слика: Дијаграм секвенце који приказује аутентификацију путем API-ја.

Корак Ток

Корак	Ток
1	API корисник шаље POST захтев ка `get-auth-token(clientId,clientSecret)` API крајњој тачки на Spotnana серверу како би генерисао и преузео привремени bearer токен. Ево примера cUrl захтева који можете користити за позив ка `get-auth-token` крајњој тачки: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Напомена: Замените вредности `clientId` и `clientSecret` са акредитивима које сте добили од Spotnana тима.
2	Spotnana сервер позива `getToken(clientId,clientSecret)` методу на Spotnana IdP-у, која генерише привремени `bearerToken` и враћа га Spotnana серверу. Spotnana сервер затим шаље овај bearer токен као JSON одговор API кориснику.

API корисник шаље POST захтев ка get-auth-token(clientId,clientSecret) API крајњој тачки на Spotnana серверу како би генерисао и преузео привремени bearer токен.

Ево примера cUrl захтева који можете користити за позив ка get-auth-token крајњој тачки:

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

Напомена: Замените вредности clientId и clientSecret са акредитивима које сте добили од Spotnana тима.

Spotnana сервер позива getToken(clientId,clientSecret) методу на Spotnana IdP-у, која генерише привремени bearerToken и враћа га Spotnana серверу.
Spotnana сервер затим шаље овај bearer токен као JSON одговор API кориснику.

Када API корисник добије bearer токен, сви наредни захтеви ка Spotnana API-јима (нпр. Trip APIs) морају садржати bearer токен у заглављу ради овлашћења.

Напомена: Крајња тачка get-auth-token(clientId, clientSecret) има ограничење од 100 API позива у периоду од 5 минута.

Аутентификација преко iFrame-а

iFrame или уграђено решење подразумева да партнери интегришу Spotnana UI у свој Partner UI, тако да корисници приступају Spotnana-у преко партнерског интерфејса. У овом сценарију, аутентификација корисника се заснива на размени токена између система партнера и Spotnana платформе.

Напомена: Код iFrame аутентификације, корисник који се пријављује назива се caller. Ово је да би се покрили специфични случајеви када се API/машински корисник пријављује и тражи access token за другог корисника. Такав API/машински корисник може користити TMC администраторске акредитиве за директну везу са Spotnana сервером. Зато ћемо у наставку користити термин caller као општи појам, који може да означава корисника који се пријављује на свој профил или API/машинског корисника који тражи access token за неког другог.

Следећи дијаграм секвенце приказује како се ток аутентификације реализује кроз размену токена између Spotnana и партнерских сервера.

Слика: Дијаграм секвенце који приказује аутентификацију преко iFrame-а уз размену токена.

Корак	Ток
Caller се пријављује преко Partner UI.
1	Partner UI приказује Spotnana UI преко iFrame-а.
2	Spotnana UI шаље захтев Partner UI-ју преко post message механизма ради преузимања токена. Захтев се шаље са `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI шаље API захтев партнерском серверу ради добијања OAuth токена, чиме почињу следећи кораци у току аутентификације.
3 а	Партнерски сервер позива Spotnana сервер користећи корисничке акредитиве и subject token као параметре. Spotnana сервер проверава да ли је захтев послат од стране API/машинског корисника.
3 б	Spotnana сервер позива партнерски сервер ради преузимања имејл адресе subject-а (caller-а). Имејл се преузима и враћа Spotnana серверу, који га користи за идентификацију корисника.
3 в	Одговор на API захтев из корака 1 Spotnana сервер шаље партнерском серверу и садржи access и refresh токен. Ови подаци се затим прослеђују Partner UI-ју.
4	Partner UI шаље токен Spotnana UI-ју преко post message механизма са `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI шаље API захтев Spotnana серверу ради генерисања и преузимања новог bearer токена. Spotnana сервер генерише bearer токен и враћа га Spotnana UI-ју. Напомена: Успешно креирање bearer токена значи да је корисник аутентификован и може приступити Spotnana-у.
6	Када је корисник аутентификован у кораку 3, сви наредни API захтеви морају садржати bearer токен, `orgId`и `tmcId` у заглављу захтева. Bearer токен се проверава у сваком долазном API захтеву, а одговор се враћа Spotnana UI-ју.

Аутентификација помоћу ауторизационог кода

Следећи дијаграм секвенце приказује како се аутентификација реализује коришћењем ауторизационог кода.

Слика: Дијаграм секвенце који приказује аутентификацију помоћу ауторизационог кода.

Корак	Ток
1	Partner UI позива партнерски сервер да добије ауторизациони код за caller-а који се пријављује. Код се враћа Partner UI-ју.
2	Partner UI шаље захтев Spotnana UI-ју преко прилагођене redirect адресе која садржи `tmcId` и `authCode` као параметре.
3	Spotnana UI шаље POST API позив Spotnana серверу користећи `v2/auth/token/companies/<tmcId>(authCode)` крајњу тачку.
3 а	Spotnana сервер шаље захтев партнерском серверу да преузме корисников `pid` користећи auth code. Корисников `pid` се преузима и шаље Spotnana серверу.
3 b	The access token and refresh token are generated by the Spotnana server and sent to Spotnana UI.
4	Spotnana UI sends a request to the Spotnana server using the access token and refresh token to generate and retrieve a bearer token for access. A bearer token is generated and sent to Spotnana UI. Note: A successful creation of bearer token indicates that the user has been authenticated and is allowed to access Spotnana.
5	Once the user is authenticated in step 4, all further API requests must contain the bearer token, the `orgId`, and the `tmcId` in the request header. The bearer token is validated in all the incoming API requests and the response is sent back to the Spotnana UI.

Note: This authentication flow cannot be used in scenarios where a TMC admin allows more than one user to use the same email when logging in.

Machine-to-machine (M2M) authentication

The M2M authentication method is suitable when the authentication flow involves the client application accessing a third-party callback URL to generate the accessToken for the user. The following sequence diagram illustrates the M2M authentication flow.

Fig: A sequence diagram explaining the M2M authentication flow.

Step	Flow
The public keys for all the applications used in the authentication are synced between Spotnana server and Spotnana IdP. This will later be used to verify the access token in the authentication flow.
1	The partner server sends an API request to `/oauth2/token(clientId,clientSecret)` in Spotnana IdP to generate a bearer token. The new bearer token is sent back to the partner server.
2	The partner server sends an API request to a third-party callback URL to generate an access token for the user. This access token is created and sent to the Spotnana server.
3	The Spotnana server validates the access token signature using the public keys synced earlier. It also validates the `claim_id` which verifies the partner’s identity. The access token is then sent to the partner server to authenticate the user.