Огляд процесів автентифікації в Spotnana

Ким створено: Ashish Chaudhary, Змінено Сб., 4 Жовт. на 9:43 ПІСЛЯ ПОЛУДНЯ автор Ashish Chaudhary

Огляд способів автентифікації Spotnana

ЗМІСТ

Огляд способів автентифікації Spotnana
- Ключові складові
- Підтримувані способи автентифікації

У Spotnana доступно кілька способів автентифікації, які дозволяють партнерам безпечно інтегруватися з нашою платформою. У цій документації наведено загальний огляд підтримуваних методів автентифікації Spotnana, а також детально описано, як саме відбувається кожен із процесів. Тут розглядаються різні сценарії автентифікації, які демонструють, як Spotnana перевіряє та надає доступ користувачам до захищених ресурсів організації (тобто ресурсів, які належать компанії користувача на платформі Spotnana).

Ключові складові

Перед початком роботи ознайомтеся з цим переліком основних компонентів системи, які згадуються у цій документації.

Інтерфейс Spotnana(Інтерфейс користувача Spotnana) Це вебзастосунок Spotnana (онлайн-інструмент для бронювання) або мобільний застосунок Spotnana. Зокрема, мається на увазі сторінка входу, яка запускає процес автентифікації при вході або створенні облікового запису.
Сервер Spotnana Це серверна частина Spotnana, яка відповідає за автентифікацію (наприклад, надання доступу до ресурсів та безпечне зберігання й обробку даних користувачів).
Інтерфейс партнера (Інтерфейс користувача партнера) Інтерфейс (тобто фронтенд-застосунок), який використовують партнери для доступу до платформи Spotnana. Наприклад, при автентифікації через iFrame, платформа Spotnana вбудовується у власний інтерфейс партнера, і користувачі працюють зі Spotnana саме через нього.
Сервер партнера Один або кілька серверів, які використовують наші партнери для інтеграції зі Spotnana.
Spotnana IdP (Постачальник ідентифікації Spotnana) Внутрішній сервіс Spotnana для керування ідентифікацією користувачів та надання їм прав доступу.
IdP партнера Сторонні постачальники ідентифікації (IdP), які використовують партнери. Серед найпоширеніших — Google та Azure.
OBT Онлайн-інструмент для бронювання Spotnana (OBT), доступний за адресою https://app.spotnana.com/
Токен суб’єкта У сценаріях автентифікації через iFrame (або токен-обмін), токен суб’єкта ідентифікує користувача. За допомогою цього токена знаходиться інформація про користувача та підтверджується його право доступу до платформи Spotnana.
Токен доступу Обліковий ключ (OAuth), який застосунок партнера використовує для доступу до захищених ресурсів від імені користувача. Це тимчасовий дозвіл, що дозволяє виконувати API-запити без розкриття пароля користувача.
Токен оновлення Довготривалий обліковий ключ, який дозволяє отримувати нові токени доступу без повторної автентифікації користувача. Зазвичай видається разом із токеном доступу під час першого входу.
Облікові дані клієнта Інформація, яку отримують користувачі для прямого підключення до API Spotnana (зокрема, унікальні clientId та clientSecret).
PID (Персональний ідентифікатор) Унікальний ідентифікатор, створений для користувача. За допомогою PID отримується інформація про користувача із сервера Spotnana.
orgId Унікальний ідентифікатор, який Spotnana присвоює організації користувача.
tmcId Унікальний ідентифікатор, який Spotnana присвоює туристичній компанії (TMC).

Підтримувані способи автентифікації

Spotnana підтримує такі способи автентифікації:

Автентифікація за паролем
- Існуючий користувач
- Новий користувач
Автентифікація через IdP
Автентифікація через API
Автентифікація через iFrame
Автентифікація за допомогою коду авторизації
Автентифікація «машина до машини» (M2M)

Автентифікація за паролем

Під час автентифікації за паролем процес входу ініціюється та керується інтерфейсом Spotnana (тобто сторінкою входу або реєстрації в OBT), який взаємодіє із сервером Spotnana. Залежно від того, чи користувач уже має профіль, чи створює новий, сценарій автентифікації може відрізнятися. Нижче наведено пояснення обох варіантів із відповідними схемами.

Існуючий користувач

Нижче наведено послідовність дій та схема, які показують, як інтерфейс Spotnana взаємодіє із серверними службами для автентифікації існуючого користувача.

Схема: Послідовна діаграма, що ілюструє автентифікацію за паролем для існуючих користувачів.

Крок	Послідовність
Існуючий користувач входить через OBT або мобільний застосунок Spotnana, використовуючи свою електронну пошту.
1	Інтерфейс Spotnana надсилає API-запит на сервер Spotnana для отримання налаштувань автентифікації користувача. У запиті передаються облікові дані користувача. У відповіді повертаються `tmcId`, `orgId`та `authProviderType`.
2	Інтерфейс Spotnana надсилає API-запит до Spotnana IdP, використовуючи `clientId`, email та пароль. Spotnana IdP генерує новий bearer-токен і повертає його інтерфейсу Spotnana. На цьому етапі користувача автентифіковано.
3	Після автентифікації в кроці 2 усі наступні API-запити мають містити bearer-токен, `orgId`та `tmcId` у заголовку запиту. Bearer-токен перевіряється у всіх вхідних API-запитах, а відповідь повертається до інтерфейсу Spotnana.

Новий користувач

Нижче наведено послідовність дій та схема, які показують, як інтерфейс Spotnana взаємодіє із серверними службами для автентифікації нового користувача (або існуючого користувача, який відновлює пароль).

Схема: Послідовна діаграма, що ілюструє автентифікацію за паролем для нових користувачів.

Крок	Послідовність
Новий користувач вводить свою електронну пошту на сторінці входу Spotnana OBT і натискає Далі.
1	Інтерфейс Spotnana надсилає API-запит на сервер Spotnana для отримання налаштувань автентифікації користувача. У запиті передаються облікові дані користувача. У відповіді повертаються `tmcId`, `orgId`та `authProviderType`.
1 a	Користувач створює новий пароль і натискає Далі.
2	Інтерфейс Spotnana надсилає API-запит до Spotnana IdP для реєстрації користувача разом із `clientId`, електронною поштою та новим паролем. Після реєстрації на електронну пошту користувача надходить одноразовий пароль (OTP).
3	Користувач вводить OTP в інтерфейсі Spotnana і натискає Підтвердити. Інтерфейс Spotnana надсилає запит до Spotnana IdP для перевірки OTP і створення bearer-токена для входу. Bearer-токен створюється і повертається інтерфейсу Spotnana. Це свідчить про успішну автентифікацію користувача для доступу до платформи Spotnana.
4	Після автентифікації в кроці 3 усі наступні API-запити мають містити bearer-токен, `orgId`та `tmcId` у заголовку запиту. Bearer-токен перевіряється у всіх вхідних API-запитах, а відповідь повертається до інтерфейсу Spotnana.

Автентифікація через IdP

Spotnana підтримує автентифікацію через IdP, такі як Google, Azure, а також власні IdP за допомогою OpenID Connect та SAML. Нижче наведено послідовність дій та схему для цього способу автентифікації.

Схема: Послідовна діаграма, що ілюструє автентифікацію через IdP.

Крок	Послідовність
Користувач входить через OBT або мобільний застосунок Spotnana, використовуючи свою електронну пошту.
1	Інтерфейс Spotnana надсилає API-запит на сервер Spotnana для отримання налаштувань автентифікації користувача. У запиті передаються облікові дані користувача. У відповіді повертаються `tmcId`, `orgId`та `authProviderType`.
2	Інтерфейс Spotnana перенаправляє запит до Spotnana IdP.
3	Spotnana IdP перенаправляє запит до IdP партнера. Це ініціює автентифікацію користувача через IdP. Примітка: Кожне перенаправлення супроводжується статус-кодом 302, який означає зміну адреси запиту.
4	Встановлюється з'єднання між Spotnana IdP та IdP партнера, щоб підтвердити автентифікацію користувача. Примітка: Під час цього з'єднання Spotnana IdP надсилає `clientId` та `clientSecret` у вигляді form URL-encoded даних через API-запит до IdP партнера. Якщо сервер IdP не підтримує цей формат, сервер Spotnana може виступати посередником і перетворювати дані у формат, який розпізнає IdP партнера.
5	IdP партнера успішно автентифікує користувача. Примітка: Після цього профіль користувача має пройти перевірку bearer-токена.
5 a	Після успішної автентифікації відповідь від IdP партнера надсилається до Spotnana IdP.
5 b	Spotnana IdP генерує унікальний код для профілю користувача і надсилає його інтерфейсу Spotnana.
6	Інтерфейс Spotnana надсилає API-запит до Spotnana IdP, використовуючи `clientID` та код, отриманий у кроці 5(b). Spotnana IdP створює новий bearer-токен і надсилає його інтерфейсу Spotnana. Примітка: Успішне створення bearer-токена означає, що користувача автентифіковано і він може працювати зі Spotnana.
7	Після автентифікації в кроці 6 усі наступні API-запити мають містити bearer-токен, `orgId`та `tmcId` у заголовку запиту. Bearer-токен перевіряється у всіх вхідних API-запитах, а відповідь повертається до інтерфейсу Spotnana.

Автентифікація через API

Партнери, які підключаються до платформи Spotnana через API, можуть використовувати наш endpoint для автентифікації, щоб згенерувати bearer-токен для своїх користувачів. Нижче наведено схему, яка ілюструє цей процес.

Схема: Послідовна діаграма, що ілюструє автентифікацію через API.

Крок Послідовність

Крок	Послідовність
1	Користувач API надсилає POST запит на `get-auth-token(clientId,clientSecret)` endpoint на сервері Spotnana, щоб згенерувати та отримати тимчасовий bearer-токен. Ось приклад cUrl-запиту для використання endpoint `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) endpoint на сервері Spotnana, щоб згенерувати та отримати тимчасовий bearer-токен.

Ось приклад cUrl-запиту для використання endpoint 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.

Після отримання bearer-токена всі подальші запити до API Spotnana (наприклад, Trip APIs) мають містити bearer-токен у заголовку для авторизації.

Примітка: Endpoint get-auth-token(clientId, clientSecret) має обмеження — не більше 100 викликів API за 5 хвилин.

Автентифікація через iFrame

iFrame або вбудоване рішення — це коли партнери інтегрують інтерфейс Spotnana у свій власний інтерфейс, і користувачі працюють зі Spotnana саме через нього. У цьому випадку автентифікація здійснюється шляхом обміну токенами між системами партнера та Spotnana.

Примітка: Для автентифікації через iFrame користувача, що входить, називатимемо caller. Це потрібно для окремих сценаріїв, коли API/машинний користувач входить і запитує токен доступу для іншого користувача. Такий API/машинний користувач може використовувати адміністраторські облікові дані TMC (туристичної компанії), щоб напряму підключитися до сервера Spotnana. Тому термін caller використовується як універсальний — це може бути як користувач, що входить у свій профіль, так і API/машинний користувач, який отримує токен для іншого.

Нижче наведено схему, яка показує, як відбувається автентифікація через обмін токенами між Spotnana та серверами партнера.

Схема: Послідовна діаграма, що ілюструє автентифікацію через iFrame із використанням обміну токенами.

Крок	Послідовність
Caller входить через інтерфейс партнера.
1	Інтерфейс партнера відображає інтерфейс Spotnana у вигляді iFrame.
2	Інтерфейс Spotnana надсилає запит до інтерфейсу партнера через post message, щоб отримати токени. У запиті вказано `type=TOKEN_EXCHANGE_REQUEST`.
3	Інтерфейс партнера надсилає API-запит до сервера партнера для отримання OAuth-токена, запускаючи наступні кроки автентифікації.
3 a	Сервер партнера звертається до сервера Spotnana, передаючи облікові дані користувача та токен суб’єкта як параметри. Сервер Spotnana перевіряє, чи запит надійшов від API/машинного користувача.
3 b	Сервер Spotnana звертається до сервера партнера, щоб отримати електронну пошту суб’єкта (caller). Електронна пошта отримується і повертається на сервер Spotnana для ідентифікації користувача.
3 c	Відповідь на API-запит із кроку 1 сервер Spotnana надсилає серверу партнера — у відповіді містяться access token та refresh token. Ці дані передаються далі до інтерфейсу партнера.
4	Інтерфейс партнера надсилає токен до інтерфейсу Spotnana через post message з `type=TOKEN_EXCHANGE_RESPONSE.`
5	Інтерфейс Spotnana надсилає API-запит на сервер Spotnana для створення та отримання нового bearer-токена. Сервер Spotnana генерує bearer-токен і повертає його інтерфейсу Spotnana. Примітка: Успішне створення bearer-токена означає, що користувача автентифіковано і він може працювати зі Spotnana.
6	Після автентифікації в кроці 3 усі наступні API-запити мають містити bearer-токен, `orgId`та `tmcId` у заголовку запиту. Bearer-токен перевіряється у всіх вхідних API-запитах, а відповідь повертається до інтерфейсу Spotnana.

Автентифікація за допомогою коду авторизації

Нижче наведено схему, яка показує, як відбувається автентифікація з використанням коду авторизації.

Схема: Послідовна діаграма, що ілюструє автентифікацію за допомогою коду авторизації.

Крок	Послідовність
1	Інтерфейс партнера звертається до сервера партнера, щоб отримати auth code для caller, який входить у систему. Auth code повертається до інтерфейсу партнера.
2	Інтерфейс партнера надсилає запит до інтерфейсу Spotnana через спеціальну redirect-URL, у якій передаються `tmcId` та `authCode` як параметри.
3	Інтерфейс Spotnana надсилає POST API-запит до сервера Spotnana на endpoint `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	Сервер Spotnana звертається до сервера партнера, щоб отримати `pid` користувача за auth code. pid `користувача отримується і повертається на сервер Spotnana.` .
3 b	Сервер Spotnana генерує access token та refresh token і надсилає їх інтерфейсу Spotnana.
4	Інтерфейс Spotnana надсилає запит до сервера Spotnana з access token та refresh token, щоб отримати bearer-токен для доступу. Bearer-токен створюється і надсилається інтерфейсу Spotnana. Примітка: Успішне створення bearer-токена означає, що користувача автентифіковано і він може працювати зі Spotnana.
5	Після автентифікації в кроці 4 усі наступні API-запити мають містити bearer-токен, `orgId`та `tmcId` у заголовку запиту. Bearer-токен перевіряється у всіх вхідних API-запитах, а відповідь повертається до інтерфейсу Spotnana.

Примітка: Цей спосіб автентифікації не підходить для ситуацій, коли адміністратор TMC дозволяє кільком користувачам входити під однією електронною поштою.

Автентифікація «машина до машини» (M2M)

Спосіб M2M підходить для сценаріїв, коли клієнтський застосунок звертається до стороннього callback-URL для генерації accessToken для користувача. Нижче наведено схему, яка ілюструє цей процес.

Схема: Послідовна діаграма, що ілюструє автентифікацію «машина до машини».

Крок	Послідовність
Публічні ключі для всіх застосунків, що беруть участь в автентифікації, синхронізуються між сервером Spotnana та Spotnana IdP. Вони використовуються для перевірки токена доступу під час автентифікації.
1	Сервер партнера надсилає API-запит на `/oauth2/token(clientId,clientSecret)` у Spotnana IdP для отримання bearer-токена. Новий bearer-токен повертається серверу партнера.
2	Сервер партнера надсилає API-запит на сторонній callback-URL для генерації access token для користувача. Access token створюється і надсилається на сервер Spotnana.
3	Сервер Spotnana перевіряє підпис access token за допомогою раніше синхронізованих публічних ключів. Також перевіряється `claim_id` що підтверджує ідентифікацію партнера. Access token далі надсилається серверу партнера для автентифікації користувача.