Преглед на начините за удостоверяване в Spotnana

Създадено от Ashish Chaudhary, Променена на Sat, 4 окт в 10:29 PM от Ashish Chaudhary

Преглед на процесите за удостоверяване в Spotnana

СЪДЪРЖАНИЕ

Преглед на процесите за удостоверяване в Spotnana
- Основни компоненти
- Поддържани методи за удостоверяване

Spotnana предлага различни методи за удостоверяване, които позволяват на партньорите да интегрират сигурно своите системи с нашата платформа. В тази документация ще намерите общ преглед на всички поддържани от Spotnana методи за удостоверяване, както и подробни обяснения на техните процеси. Описаните по-долу потоци показват как Spotnana удостоверява и разрешава достъп на потребители до защитени ресурси на ниво организация (т.е. ресурсите, собственост на фирмата на потребителя в платформата Spotnana).

Основни компоненти

Преди да започнете, запознайте се с този списък с дефиниции на основните системни компоненти, които се споменават в документацията.

Spotnana UI(Потребителски интерфейс на Spotnana) Отнася се до уеб приложението на Spotnana (т.е. онлайн инструмента за резервации) или мобилното приложение на Spotnana. По-конкретно, това е страницата за вход, която стартира процеса по удостоверяване, когато потребителят се вписва или създава нов профил.
Сървър на Spotnana Това е бекенд сървърът на Spotnana, който се използва за удостоверяване – например за разрешаване на достъп до ресурси и за сигурно съхранение и обработка на потребителска информация.
Партньорски UI (Потребителски интерфейс на партньора) Това е интерфейсът (т.е. фронтенд приложението), който партньорите използват, за да достъпят платформата на Spotnana. Например, при удостоверяване чрез iFrame, Spotnana се вгражда в потребителския интерфейс на партньора и неговите потребители работят със Spotnana през този интерфейс.
Партньорски сървър Това са един или повече бекенд сървъри, които партньорите използват за интеграция със Spotnana.
Spotnana IdP (Доставчик на идентичност на Spotnana) Вътрешна услуга на Spotnana за управление на потребителски идентичности и разрешения.
Партньорски IdP Външни доставчици на идентичност (IdP), които партньорите използват. Често срещани примери са 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 Данни, предоставени на потребители, които се свързват директно с API-тата на Spotnana (т.е. уникални clientId и clientSecret).
PID (Личен идентификатор) Уникален идентификатор, създаден за потребителя. Чрез PID се извлича информацията за потребителя от сървъра на Spotnana.
orgId Уникален идентификатор, който Spotnana присвоява на организацията на потребителя.
tmcId Уникален идентификатор, който Spotnana присвоява на TMC (фирма за управление на пътувания).

Поддържани методи за удостоверяване

Spotnana поддържа следните методи за удостоверяване:

Удостоверяване с парола
- Съществуващ потребител
- Нов потребител
Удостоверяване чрез IdP
Удостоверяване чрез API
Удостоверяване чрез iFrame
Удостоверяване чрез auth код
Удостоверяване между машини (M2M)

Удостоверяване с парола

При удостоверяване с парола, Spotnana UI (т.е. страницата за вход или регистрация в OBT) стартира и управлява процеса по удостоверяване с бекенд сървърите на Spotnana. В зависимост от това дали потребителят се вписва с вече съществуващ профил или създава нов, процесът може да протече по два различни начина. И двата сценария са обяснени по-долу с помощта на последователни диаграми.

Съществуващ потребител

Диаграмата и стъпките по-долу показват как Spotnana UI взаимодейства с бекенд услугите, за да удостовери съществуващ потребител.

Фиг.: Последователна диаграма, илюстрираща удостоверяването с парола за съществуващи потребители.

Стъпка	Поток
Съществуващ потребител се вписва през OBT или мобилното приложение на Spotnana, използвайки своя имейл.
1	Spotnana UI изпраща API заявка към сървъра на Spotnana, за да получи информация за конфигурацията на удостоверяването за този потребител. Заявката съдържа данните за вход на потребителя. В отговора се съдържат `tmcId`, `orgId`и `authProviderType`.
2	Spotnana UI изпраща API заявка към Spotnana IdP, като използва `clientId`, имейл и парола. Spotnana IdP генерира нов bearer token и го връща на Spotnana UI. На този етап потребителят е успешно удостоверен.
3	След като потребителят бъде удостоверен на стъпка 2, всички следващи API заявки трябва да съдържат bearer token, както и `orgId`и `tmcId` в хедъра на заявката. При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.

Нов потребител

Диаграмата и стъпките по-долу показват как Spotnana UI взаимодейства с бекенд услугите, за да удостовери нов потребител (или съществуващ потребител, който иска да възстанови паролата си).

Фиг.: Последователна диаграма, илюстрираща удостоверяването с парола за нови потребители.

Стъпка	Поток
Нов потребител въвежда своя имейл на страницата за вход в Spotnana OBT и избира Next.
1	Spotnana UI изпраща API заявка към сървъра на Spotnana, за да получи информация за конфигурацията на удостоверяването за този потребител. Заявката съдържа данните за вход на потребителя. В отговора се съдържат `tmcId`, `orgId`и `authProviderType`.
1 a	Потребителят въвежда нова парола и избира Next.
2	Spotnana UI изпраща API заявка към Spotnana IdP за регистрация на потребителя, като подава `clientId`, имейл и нова парола. След като данните бъдат регистрирани, на имейла на потребителя се изпраща еднократна парола (OTP).
3	Потребителят въвежда OTP в Spotnana UI и избира Verify. Spotnana UI изпраща заявка към Spotnana IdP за потвърждение на OTP и генериране на bearer token за вход. Bearer token-ът се генерира и връща на Spotnana UI. Това означава, че удостоверяването е успешно и потребителят може да достъпи платформата Spotnana чрез този токен.
4	След като потребителят е удостоверен на стъпка 3, всички следващи API заявки трябва да съдържат bearer token, както и `orgId`и `tmcId` в хедъра на заявката. При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.

Удостоверяване чрез IdP

Spotnana поддържа удостоверяване чрез IdP като Google, Azure и други, използвайки OpenID Connect и SAML протоколи. Диаграмата и стъпките по-долу показват как протича удостоверяването чрез IdP.

Фиг.: Последователна диаграма, илюстрираща удостоверяването чрез IdP.

Стъпка	Поток
Потребителят се вписва през OBT или мобилното приложение на Spotnana, използвайки своя имейл.
1	Spotnana UI изпраща API заявка към сървъра на Spotnana, за да получи информация за конфигурацията на удостоверяването за този потребител. Заявката съдържа данните за вход на потребителя. В отговора се съдържат `tmcId`, `orgId`и]]></и> <i idx='146'><![CDATA[authProviderType `authProviderType`.
2	Spotnana UI пренасочва заявката към Spotnana IdP.
3	Spotnana IdP пренасочва заявката към IdP на партньора. Така започва удостоверяването чрез IdP. Забележка: При всяко пренасочване се връща статус код 302, който показва, че заявката е пренасочена към друг адрес.
4	Установява се връзка между Spotnana IdP и IdP на партньора, за да се потвърди, че потребителят е удостоверен от партньорския IdP. Забележка: По време на тази връзка Spotnana IdP изпраща `clientId` и `clientSecret` като данни във формат form URL-encoded чрез API заявка към IdP на партньора. Ако IdP не може да обработи този формат, сървърът на Spotnana може да действа като посредник и да преобразува данните в подходящ вид.
5	IdP на партньора успешно удостоверява потребителя. Забележка: След тази стъпка профилът на потребителя трябва да премине и през проверка на bearer token.
5 a	След успешно удостоверяване, отговорът от IdP на партньора се изпраща към Spotnana IdP.
5 b	Spotnana IdP генерира уникален код за профила на потребителя и го изпраща към Spotnana UI.
6	Spotnana UI изпраща API заявка към Spotnana IdP, като използва `clientID` и кода, получен на стъпка 5(b). Spotnana IdP генерира нов bearer token и го изпраща към Spotnana UI. Забележка: Успешното създаване на bearer token означава, че потребителят е удостоверен и има достъп до Spotnana.
7	След като потребителят е удостоверен на стъпка 6, всички следващи API заявки трябва да съдържат bearer token, както и]]></и> <i idx='179'><![CDATA[orgId `orgId`и `tmcId]]></и> <i idx='182'><![CDATA[в хедъра на заявката.` in the request header. При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.

Удостоверяване чрез API

Партньорите, които използват API-тата на Spotnana за интеграция с платформата, могат да генерират bearer token за своите потребители чрез специален endpoint за удостоверяване. Следващата диаграма показва как протича този процес.

Фиг.: Последователна диаграма, илюстрираща удостоверяването чрез API.]]></и> <![CDATA[Стъпка

Step Поток]]></и> <![CDATA[1

Step	Поток]]></и> <i idx='190'><![CDATA[1
1	API потребителят прави POST]]></и> <i idx='193'><![CDATA[заявка към]]></и> <i idx='194'><![CDATA[get-auth-token(clientId,clientSecret)]]></и> <i idx='195'><![CDATA[API endpoint на сървъра на Spotnana, за да генерира и получи временен bearer token.]]></и> <i idx='196'><![CDATA[Ето примерна cUrl заявка, която може да използвате към endpoint-а]]></и> <i idx='197'><![CDATA[get-auth-token]]></и> <i idx='198'><![CDATA[:]]></и> <i idx='199'><![CDATA[curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }']]></и> <i idx='200'><![CDATA[Забележка:]]></и> <i idx='201'><![CDATA[Заменете стойностите за]]></и> <i idx='202'><![CDATA[clientId]]></и> <i idx='203'><![CDATA[и]]></и> <i idx='204'><![CDATA[clientSecret]]></и> <i idx='205'><![CDATA[с вашите данни, които сте получили от Spotnana.]]></и> <i idx='206'><![CDATA[2]]></и> <i idx='207'><![CDATA[Сървърът на Spotnana извиква метода]]></и> <i idx='208'><![CDATA[getToken(clientId,clientSecret)]]></и> <i idx='209'><![CDATA[в Spotnana IdP, който генерира временен]]></и> <i idx='210'><![CDATA[bearerToken]]></и> <i idx='211'><![CDATA[и го връща към сървъра на Spotnana.]]></и> <i idx='212'><![CDATA[Сървърът на Spotnana изпраща този bearer token като JSON отговор към API потребителя.]]></и> <i idx='213'><![CDATA[След като API потребителят получи bearer token, всички следващи заявки към Spotnana API (например]]></и> <i idx='214'><![CDATA[Trip APIs]]></и> <i idx='215'><![CDATA[) трябва да съдържат bearer token в хедъра за авторизация.]]></и> <i idx='216'><![CDATA[Забележка:]]></и> <i idx='217'><![CDATA[Endpoint-ът]]></и> <i idx='218'><![CDATA[get-auth-token(clientId, clientSecret)]]></и> <i idx='219'><![CDATA[има лимит от 100 API заявки на всеки 5 минути.]]></и> <i idx='220'><![CDATA[Удостоверяване чрез iFrame]]></и> <i idx='221'><![CDATA[iFrame или вградено решение означава, че партньорите вграждат Spotnana UI в своя потребителски интерфейс, така че потребителите достъпват Spotnana през интерфейса на партньора. В този случай удостоверяването на потребителя се осъществява чрез обмен на токени между системите на партньора и Spotnana.]]></и> <i idx='222'><![CDATA[Забележка]]></и> <i idx='223'><![CDATA[: При удостоверяване чрез iFrame, потребителят, който се вписва, ще бъде наричан]]></и> <i idx='224'><![CDATA[caller]]></и> <i idx='225'><![CDATA[. Това позволява специфични сценарии, при които API/машинен потребител се вписва и иска access token за друг потребител. Такъв потребител може да използва администраторски данни на TMC, за да се свърже директно със сървъра на Spotnana. Затова ще използваме]]></и> <i idx='226'><![CDATA[caller]]></и> <i idx='227'><![CDATA[като обобщен термин – може да е потребител, който влиза в собствения си профил, или API/машинен потребител, който иска токен за друг.]]></и> <i idx='228'><![CDATA[Следващата диаграма показва как протича удостоверяването чрез обмен на токени между Spotnana и сървърите на партньора.]]></и> <i idx='229'><![CDATA[Фиг.:]]></и> <i idx='230'><![CDATA[Последователна диаграма, илюстрираща удостоверяването чрез iFrame и обмен на токени.]]></и> <i idx='231'><![CDATA[Стъпка]]></и> <i idx='232'><![CDATA[Поток]]></и> <i idx='233'><![CDATA[Caller се вписва през Partner UI.]]></и> <i idx='234'><![CDATA[1]]></и> <i idx='235'><![CDATA[Партньорският UI зарежда Spotnana UI чрез iFrame.]]></и> <i idx='236'><![CDATA[2]]></и> <i idx='237'><![CDATA[Spotnana UI изпраща заявка към Partner UI чрез post message, за да получи токени. Заявката се изпраща с]]></и> <i idx='238'><![CDATA[type=TOKEN_EXCHANGE_REQUEST]]></и> <i idx='239'><![CDATA[.]]></и> <i idx='240'><![CDATA[3]]></и> <i idx='241'><![CDATA[Partner UI изпраща API заявка към партньорския сървър, за да получи OAuth токен, с което стартира следващите стъпки по удостоверяването.]]></и> <i idx='242'><![CDATA[3 a]]></и> <i idx='243'><![CDATA[Партньорският сървър извиква Spotnana сървъра, като подава потребителски данни и subject token като параметри. Spotnana проверява дали заявката идва от API/машинен потребител.]]></и> <i idx='244'><![CDATA[3 b]]></и> <i idx='245'><![CDATA[Сървърът на Spotnana извиква партньорския сървър, за да получи имейла на subject (caller).]]></и> <i idx='246'><![CDATA[Имейлът се връща към Spotnana сървъра и се използва за идентифициране на потребителя.]]></и> <i idx='247'><![CDATA[3 c]]></и> <i idx='248'><![CDATA[Отговорът на API заявката от стъпка 1 се връща от Spotnana към партньорския сървър и съдържа access token и refresh token.]]></и> <i idx='249'><![CDATA[Тези данни се изпращат към Partner UI.]]></и> <i idx='250'><![CDATA[4]]></и> <i idx='251'><![CDATA[Partner UI изпраща токена към Spotnana UI чрез post message с]]></и> <i idx='252'><![CDATA[type=TOKEN_EXCHANGE_RESPONSE.]]></и> <i idx='253'><![CDATA[5]]></и> <i idx='254'><![CDATA[Spotnana UI изпраща API заявка към Spotnana сървъра, за да генерира и получи нов bearer token.]]></и> <i idx='255'><![CDATA[Сървърът на Spotnana генерира bearer token и го връща към Spotnana UI.]]></и> <i idx='256'><![CDATA[Забележка:]]></и> <i idx='257'><![CDATA[Успешното създаване на bearer token означава, че потребителят е удостоверен и има достъп до Spotnana.]]></и> <i idx='258'><![CDATA[6]]></и> <i idx='259'><![CDATA[След като потребителят е удостоверен на стъпка 3, всички следващи API заявки трябва да съдържат bearer token, както и]]></и> <i idx='260'><![CDATA[orgId]]></и> <i idx='261'><![CDATA[и]]></и> <i idx='262'><![CDATA[tmcId]]></и> <i idx='263'><![CDATA[в хедъра на заявката.]]></и> <i idx='264'><![CDATA[При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.]]></и> <i idx='265'><![CDATA[Удостоверяване чрез auth код]]></и> <i idx='266'><![CDATA[Следващата диаграма показва как протича удостоверяването чрез авторизационен код.]]></и> <i idx='267'><![CDATA[Фиг.:]]></и> <i idx='268'><![CDATA[Последователна диаграма, илюстрираща удостоверяването чрез auth код.]]></и> <i idx='269'><![CDATA[Стъпка]]></и> <i idx='270'><![CDATA[Поток]]></и> <i idx='271'><![CDATA[1]]></и> <i idx='272'><![CDATA[Partner UI извиква партньорския сървър, за да получи auth код за caller-а, който се вписва. Кодът се връща към Partner UI.]]></и> <i idx='273'><![CDATA[2]]></и> <i idx='274'><![CDATA[Partner UI изпраща заявка към Spotnana UI чрез custom redirect URL, който съдържа]]></и> <i idx='275'><![CDATA[tmcId]]></и> <i idx='276'><![CDATA[и]]></и> <i idx='277'><![CDATA[authCode]]></и> <i idx='278'><![CDATA[като параметри.]]></и> <i idx='279'><![CDATA[3]]></и> <i idx='280'><![CDATA[Spotnana UI прави]]></и> <i idx='281'><![CDATA[POST]]></и> <i idx='282'><![CDATA[API заявка към Spotnana сървъра, използвайки]]></и> <i idx='283'><![CDATA[v2/auth/token/companies/<tmcId>(authCode)]]></и> <i idx='284'><![CDATA[API endpoint.]]></и> <i idx='285'><![CDATA[3 a]]></и> <i idx='286'><![CDATA[Spotnana сървърът изпраща заявка към партньорския сървър, за да получи]]></и> <i idx='287'><![CDATA[pid]]></и> <i idx='288'><![CDATA[на потребителя, използвайки auth кода.]]></и> <i idx='289'><![CDATA[pid]]></и> <i idx='290'><![CDATA[на потребителя се връща към Spotnana сървъра.]]></и> <i idx='291'><![CDATA[3 b]]></и> <i idx='292'><![CDATA[Access token и refresh token се генерират от Spotnana сървъра и се изпращат към Spotnana UI.]]></и> <i idx='293'><![CDATA[4]]></и> <i idx='294'><![CDATA[Spotnana UI изпраща заявка към Spotnana сървъра с access token и refresh token, за да генерира и получи bearer token за достъп.]]></и> <i idx='295'><![CDATA[Генерира се bearer token, който се връща към Spotnana UI.]]></и> <i idx='296'><![CDATA[Забележка:]]></и> <i idx='297'><![CDATA[Успешното създаване на bearer token означава, че потребителят е удостоверен и има достъп до Spotnana.]]></и> <i idx='298'><![CDATA[5]]></и> <i idx='299'><![CDATA[След като потребителят е удостоверен на стъпка 4, всички следващи API заявки трябва да съдържат bearer token, както и]]></и> <i idx='300'><![CDATA[orgId]]></и> <i idx='301'><![CDATA[и]]></и> <i idx='302'><![CDATA[tmcId]]></и> <i idx='303'><![CDATA[в хедъра на заявката.]]></и> <i idx='304'><![CDATA[При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.]]></и> <i idx='305'><![CDATA[Забележка:]]></и> <i idx='306'><![CDATA[Този поток за удостоверяване не е приложим, ако TMC администратор позволява повече от един потребител да използва един и същ имейл за вход.]]></и> <i idx='307'><![CDATA[Удостоверяване между машини (M2M)]]></и> <i idx='308'><![CDATA[M2M удостоверяването е подходящо, когато клиентското приложение трябва да достъпи външен callback URL, за да генерира]]></и> <i idx='309'><![CDATA[accessToken]]></и> <i idx='310'><![CDATA[за потребителя. Следващата диаграма показва как протича този процес.]]></и> <i idx='311'><![CDATA[Фиг.:]]></и> <i idx='312'><![CDATA[Последователна диаграма, илюстрираща M2M удостоверяването.]]></и> <i idx='313'><![CDATA[Стъпка]]></и> <i idx='314'><![CDATA[Поток]]></и> <i idx='315'><![CDATA[Публичните ключове за всички приложения, които участват в удостоверяването, се синхронизират между сървъра на Spotnana и Spotnana IdP. Те ще се използват по-късно за проверка на access token в потока по удостоверяване.]]></и> <i idx='316'><![CDATA[1]]></и> <i idx='317'><![CDATA[Партньорският сървър изпраща API заявка към]]></и> <i idx='318'><![CDATA[/oauth2/token(clientId,clientSecret)]]></и> <i idx='319'><![CDATA[в Spotnana IdP, за да генерира bearer token. Новият bearer token се връща на партньорския сървър.]]></и> <i idx='320'><![CDATA[2]]></и> <i idx='321'><![CDATA[Партньорският сървър изпраща API заявка към външен callback URL, за да генерира access token за потребителя.]]></и> <i idx='322'><![CDATA[Access token-ът се създава и изпраща към сървъра на Spotnana.]]></и> <i idx='323'><![CDATA[3]]></и> <i idx='324'><![CDATA[Сървърът на Spotnana валидира подписа на access token с помощта на предварително синхронизираните публични ключове. Също така валидира]]></и> <i idx='325'><![CDATA[claim_id]]></и> <i idx='326'><![CDATA[който потвърждава идентичността на партньора.]]></и> <i idx='327'><![CDATA[Access token-ът се изпраща към партньорския сървър за удостоверяване на потребителя.]]></и> <i idx='328'><![CDATA[... call to the `get-auth-token(clientId,clientSecret)` API endpoint in the Spotnana server to generate and retrieve a temporary bearer token. Heres a sample cUrl request to use when calling the `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>" }' Note: Replace the `clientId` and `clientSecret` values with the credentials you have received from Spotnana.
2	The Spotnana server calls the `getToken(clientId,clientSecret)` method in the Spotnana IdP, which generates a temporary `bearerToken` and sends it back to the Spotnana server. The Spotnana server sends this bearer token as a JSON response to the API user.

API потребителят прави POST]]></и> <![CDATA[заявка към]]></и> <![CDATA[get-auth-token(clientId,clientSecret)]]></и> <![CDATA[API endpoint на сървъра на Spotnana, за да генерира и получи временен bearer token.]]></и> <![CDATA[Ето примерна cUrl заявка, която може да използвате към endpoint-а]]></и> <![CDATA[get-auth-token]]></и> <![CDATA[:]]></и> <![CDATA[curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }']]></и> <![CDATA[Забележка:]]></и> <![CDATA[Заменете стойностите за]]></и> <![CDATA[clientId]]></и> <![CDATA[и]]></и> <![CDATA[clientSecret]]></и> <![CDATA[с вашите данни, които сте получили от Spotnana.]]></и> <![CDATA[2]]></и> <![CDATA[Сървърът на Spotnana извиква метода]]></и> <![CDATA[getToken(clientId,clientSecret)]]></и> <![CDATA[в Spotnana IdP, който генерира временен]]></и> <![CDATA[bearerToken]]></и> <![CDATA[и го връща към сървъра на Spotnana.]]></и> <![CDATA[Сървърът на Spotnana изпраща този bearer token като JSON отговор към API потребителя.]]></и> <![CDATA[След като API потребителят получи bearer token, всички следващи заявки към Spotnana API (например]]></и> <![CDATA[Trip APIs]]></и> <![CDATA[) трябва да съдържат bearer token в хедъра за авторизация.]]></и> <![CDATA[Забележка:]]></и> <![CDATA[Endpoint-ът]]></и> <![CDATA[get-auth-token(clientId, clientSecret)]]></и> <![CDATA[има лимит от 100 API заявки на всеки 5 минути.]]></и> <![CDATA[Удостоверяване чрез iFrame]]></и> <![CDATA[iFrame или вградено решение означава, че партньорите вграждат Spotnana UI в своя потребителски интерфейс, така че потребителите достъпват Spotnana през интерфейса на партньора. В този случай удостоверяването на потребителя се осъществява чрез обмен на токени между системите на партньора и Spotnana.]]></и> <![CDATA[Забележка]]></и> <![CDATA[: При удостоверяване чрез iFrame, потребителят, който се вписва, ще бъде наричан]]></и> <![CDATA[caller]]></и> <![CDATA[. Това позволява специфични сценарии, при които API/машинен потребител се вписва и иска access token за друг потребител. Такъв потребител може да използва администраторски данни на TMC, за да се свърже директно със сървъра на Spotnana. Затова ще използваме]]></и> <![CDATA[caller]]></и> <![CDATA[като обобщен термин – може да е потребител, който влиза в собствения си профил, или API/машинен потребител, който иска токен за друг.]]></и> <![CDATA[Следващата диаграма показва как протича удостоверяването чрез обмен на токени между Spotnana и сървърите на партньора.]]></и> <![CDATA[Фиг.:]]></и> <![CDATA[Последователна диаграма, илюстрираща удостоверяването чрез iFrame и обмен на токени.]]></и> <![CDATA[Стъпка]]></и> <![CDATA[Поток]]></и> <![CDATA[Caller се вписва през Partner UI.]]></и> <![CDATA[1]]></и> <![CDATA[Партньорският UI зарежда Spotnana UI чрез iFrame.]]></и> <![CDATA[2]]></и> <![CDATA[Spotnana UI изпраща заявка към Partner UI чрез post message, за да получи токени. Заявката се изпраща с]]></и> <![CDATA[type=TOKEN_EXCHANGE_REQUEST]]></и> <![CDATA[.]]></и> <![CDATA[3]]></и> <![CDATA[Partner UI изпраща API заявка към партньорския сървър, за да получи OAuth токен, с което стартира следващите стъпки по удостоверяването.]]></и> <![CDATA[3 a]]></и> <![CDATA[Партньорският сървър извиква Spotnana сървъра, като подава потребителски данни и subject token като параметри. Spotnana проверява дали заявката идва от API/машинен потребител.]]></и> <![CDATA[3 b]]></и> <![CDATA[Сървърът на Spotnana извиква партньорския сървър, за да получи имейла на subject (caller).]]></и> <![CDATA[Имейлът се връща към Spotnana сървъра и се използва за идентифициране на потребителя.]]></и> <![CDATA[3 c]]></и> <![CDATA[Отговорът на API заявката от стъпка 1 се връща от Spotnana към партньорския сървър и съдържа access token и refresh token.]]></и> <![CDATA[Тези данни се изпращат към Partner UI.]]></и> <![CDATA[4]]></и> <![CDATA[Partner UI изпраща токена към Spotnana UI чрез post message с]]></и> <![CDATA[type=TOKEN_EXCHANGE_RESPONSE.]]></и> <![CDATA[5]]></и> <![CDATA[Spotnana UI изпраща API заявка към Spotnana сървъра, за да генерира и получи нов bearer token.]]></и> <![CDATA[Сървърът на Spotnana генерира bearer token и го връща към Spotnana UI.]]></и> <![CDATA[Забележка:]]></и> <![CDATA[Успешното създаване на bearer token означава, че потребителят е удостоверен и има достъп до Spotnana.]]></и> <![CDATA[6]]></и> <![CDATA[След като потребителят е удостоверен на стъпка 3, всички следващи API заявки трябва да съдържат bearer token, както и]]></и> <![CDATA[orgId]]></и> <![CDATA[и]]></и> <![CDATA[tmcId]]></и> <![CDATA[в хедъра на заявката.]]></и> <![CDATA[При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.]]></и> <![CDATA[Удостоверяване чрез auth код]]></и> <![CDATA[Следващата диаграма показва как протича удостоверяването чрез авторизационен код.]]></и> <![CDATA[Фиг.:]]></и> <![CDATA[Последователна диаграма, илюстрираща удостоверяването чрез auth код.]]></и> <![CDATA[Стъпка]]></и> <![CDATA[Поток]]></и> <![CDATA[1]]></и> <![CDATA[Partner UI извиква партньорския сървър, за да получи auth код за caller-а, който се вписва. Кодът се връща към Partner UI.]]></и> <![CDATA[2]]></и> <![CDATA[Partner UI изпраща заявка към Spotnana UI чрез custom redirect URL, който съдържа]]></и> <![CDATA[tmcId]]></и> <![CDATA[и]]></и> <![CDATA[authCode]]></и> <![CDATA[като параметри.]]></и> <![CDATA[3]]></и> <![CDATA[Spotnana UI прави]]></и> <![CDATA[POST]]></и> <![CDATA[API заявка към Spotnana сървъра, използвайки]]></и> <![CDATA[v2/auth/token/companies/<tmcId>(authCode)]]></и> <![CDATA[API endpoint.]]></и> <![CDATA[3 a]]></и> <![CDATA[Spotnana сървърът изпраща заявка към партньорския сървър, за да получи]]></и> <![CDATA[pid]]></и> <![CDATA[на потребителя, използвайки auth кода.]]></и> <![CDATA[pid]]></и> <![CDATA[на потребителя се връща към Spotnana сървъра.]]></и> <![CDATA[3 b]]></и> <![CDATA[Access token и refresh token се генерират от Spotnana сървъра и се изпращат към Spotnana UI.]]></и> <![CDATA[4]]></и> <![CDATA[Spotnana UI изпраща заявка към Spotnana сървъра с access token и refresh token, за да генерира и получи bearer token за достъп.]]></и> <![CDATA[Генерира се bearer token, който се връща към Spotnana UI.]]></и> <![CDATA[Забележка:]]></и> <![CDATA[Успешното създаване на bearer token означава, че потребителят е удостоверен и има достъп до Spotnana.]]></и> <![CDATA[5]]></и> <![CDATA[След като потребителят е удостоверен на стъпка 4, всички следващи API заявки трябва да съдържат bearer token, както и]]></и> <![CDATA[orgId]]></и> <![CDATA[и]]></и> <![CDATA[tmcId]]></и> <![CDATA[в хедъра на заявката.]]></и> <![CDATA[При всяка входяща API заявка bearer token-ът се валидира и отговорът се връща към Spotnana UI.]]></и> <![CDATA[Забележка:]]></и> <![CDATA[Този поток за удостоверяване не е приложим, ако TMC администратор позволява повече от един потребител да използва един и същ имейл за вход.]]></и> <![CDATA[Удостоверяване между машини (M2M)]]></и> <![CDATA[M2M удостоверяването е подходящо, когато клиентското приложение трябва да достъпи външен callback URL, за да генерира]]></и> <![CDATA[accessToken]]></и> <![CDATA[за потребителя. Следващата диаграма показва как протича този процес.]]></и> <![CDATA[Фиг.:]]></и> <![CDATA[Последователна диаграма, илюстрираща M2M удостоверяването.]]></и> <![CDATA[Стъпка]]></и> <![CDATA[Поток]]></и> <![CDATA[Публичните ключове за всички приложения, които участват в удостоверяването, се синхронизират между сървъра на Spotnana и Spotnana IdP. Те ще се използват по-късно за проверка на access token в потока по удостоверяване.]]></и> <![CDATA[1]]></и> <![CDATA[Партньорският сървър изпраща API заявка към]]></и> <![CDATA[/oauth2/token(clientId,clientSecret)]]></и> <![CDATA[в Spotnana IdP, за да генерира bearer token. Новият bearer token се връща на партньорския сървър.]]></и> <![CDATA[2]]></и> <![CDATA[Партньорският сървър изпраща API заявка към външен callback URL, за да генерира access token за потребителя.]]></и> <![CDATA[Access token-ът се създава и изпраща към сървъра на Spotnana.]]></и> <![CDATA[3]]></и> <![CDATA[Сървърът на Spotnana валидира подписа на access token с помощта на предварително синхронизираните публични ключове. Също така валидира]]></и> <![CDATA[claim_id]]></и> <![CDATA[който потвърждава идентичността на партньора.]]></и> <![CDATA[Access token-ът се изпраща към партньорския сървър за удостоверяване на потребителя.]]></и> <![CDATA[... call to the get-auth-token(clientId,clientSecret) API endpoint in the Spotnana server to generate and retrieve a temporary bearer token.

Heres a sample cUrl request to use when calling the 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>"
}'

Note: Replace the clientId and clientSecret values with the credentials you have received from Spotnana.

The Spotnana server calls the getToken(clientId,clientSecret) method in the Spotnana IdP, which generates a temporary bearerToken and sends it back to the Spotnana server.
The Spotnana server sends this bearer token as a JSON response to the API user.

Once the API user has received the bearer token, all the subsequent requests made to Spotnana APIs (e.g., Trip APIs) must include the bearer token in the header for authorization.

Note: The get-auth-token(clientId, clientSecret) endpoint has a rate limit of 100 API calls per 5 minutes.

iFrame-based authentication

An iFrame or an embedded solution is when partners embed the Spotnana UI into the partner UI, which means users access Spotnana via the partner UI. In this scenario, the user authentication is handled based on token exchange between the partner and Spotnana systems.

Note: For iFrame-based authentication, the user logging in will be referred to as a caller. This is to allow for specific scenarios where an API/Machine user logs in and requests an access token for another user. This API/Machine user could use TMC (Travel Management Company) admin credentials to connect directly with the Spotnana server. Hence, we’ll be using caller as a generalized term, which can refer to a user logging into their own profile or an API/Machine user requesting an access token for another user.

The following sequence diagram illustrates how the authentication flow is handled using a token exchange between Spotnana and the partner servers.

Fig: A sequence diagram explaining the iFrame-based authentication using token exchange.

Step	Flow
A caller logs in using the Partner UI.
1	The partner UI renders the Spotnana UI via iFrame.
2	The Spotnana UI sends a request to partner UI via a post message to retrieve tokens. The request is sent with `type=TOKEN_EXCHANGE_REQUEST`.
3	The Partner UI sends an API request to the partner server to retrieve the OAuth token, initiating the next consecutive steps in the authentication flow.
3 a	The partner server calls the Spotnana server using the user credentials and the subject token as parameters. The Spotnana server checks if the incoming request is sent by an API/Machine user.
3 b	The Spotnana server calls the partner server to retrieve the subject (i.e., the caller) email. The email is fetched and returned to the Spotnana server, which is used to identify the user.
3 c	The response to the API request from step 1 is sent by the Spotnana server to the partner server containing the access token and the refresh token. These details are then sent to the Partner UI.
4	The partner UI sends the token to Spotnana UI via a post message with `type=TOKEN_EXCHANGE_RESPONSE.`
5	The Spotnana UI sends an API request to the Spotnana server to generate and retrieve a new bearer token. A bearer token is generated by the Spotnana server and returned to the Spotnana UI. Note: A successful creation of bearer token indicates that the user has been authenticated and is allowed to access Spotnana.
6	Once the user is authenticated in step 3, 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.

Auth code-based authentication

The following sequence diagram illustrates how the authentication flow is handled using an authorization code.

Fig: A sequence diagram explaining the auth code-based authentication using auth code.

Step	Flow
1	The partner UI calls the partner server to retrieve the auth code for the caller logging in. The auth code is retrieved and sent back to the partner UI.
2	The Partner UI sends a request to the Spotnana UI using a custom redirect URL containing the `tmcId` and `authCode` as parameters.
3	Spotnana UI makes a POST API call to Spotnana server using the `v2/auth/token/companies/<tmcId>(authCode)` API endpoint.
3 a	Spotnana server sends a request to partner server to retrieve the user’s `pid` using the auth code. The user’s `pid` is retrieved and sent to the Spotnana server.
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.