Обзор способов авторизации в Spotnana

Создано: Ashish Chaudhary, Изменено Вск, 5 Окт на 1:20 AM по Ashish Chaudhary

Обзор способов аутентификации в Spotnana

СОДЕРЖАНИЕ

Обзор способов аутентификации в Spotnana
- Основные компоненты
- Поддерживаемые способы аутентификации

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

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

Перед началом работы ознакомьтесь с этим списком — здесь объясняются ключевые компоненты системы, которые упоминаются в документации.

Spotnana UI(Пользовательский интерфейс Spotnana) Это веб-приложение Spotnana (онлайн-система бронирования) или мобильное приложение Spotnana. В данном контексте речь идет о странице входа, которая запускает процесс аутентификации при входе пользователя или создании новой учетной записи.
Сервер Spotnana Это серверная часть Spotnana, которая отвечает за аутентификацию (например, разрешает доступ к ресурсам и безопасно хранит данные пользователей).
Партнерский UI (Пользовательский интерфейс партнера) Это интерфейс (то есть клиентское приложение), через который партнеры получают доступ к платформе Spotnana. Например, при аутентификации через iFrame платформа Spotnana встраивается в интерфейс партнера, и пользователи заходят в Spotnana через этот UI.
Сервер партнера Это один или несколько серверов, которые партнеры используют для интеграции с Spotnana.
Spotnana IdP (Провайдер идентификации Spotnana) Внутренний сервис Spotnana для управления учетными записями пользователей и их авторизацией.
IdP партнера Сторонние провайдеры идентификации (IdP), которыми пользуются партнеры. К примеру, Google или Azure.
OBT Онлайн-система бронирования Spotnana (OBT), доступная по адресу https://app.spotnana.com/
Токен субъекта При аутентификации через iFrame (или обмен токенами) токен субъекта подтверждает личность пользователя. С помощью этого токена система получает информацию о пользователе и дает ему доступ к платформе Spotnana.
Токен доступа Это временный ключ (OAuth), который приложение-партнер использует для доступа к защищённым ресурсам от имени пользователя. Такой токен позволяет делать запросы к API без передачи пароля пользователя.
Refresh token (токен обновления) Долгоживущий токен, с помощью которого можно получить новый токен доступа без повторной аутентификации пользователя. Обычно он выдается вместе с токеном доступа при первом входе.
Client credentials (клиентские данные) Данные, которые выдаются пользователям для прямого подключения к API Spotnana (например, уникальные clientId и clientSecret).
PID (Персональный идентификатор) Уникальный идентификатор пользователя, с помощью которого сервер Spotnana находит информацию о нем.
orgId Уникальный идентификатор организации пользователя, который присваивается Spotnana.
tmcId Уникальный идентификатор, который Spotnana выдает для TMC (туристической компании).

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

Spotnana поддерживает следующие способы аутентификации:

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

Аутентификация по паролю

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

Существующий пользователь

Ниже показаны диаграмма последовательности и шаги, которые объясняют, как Spotnana UI взаимодействует с сервером для аутентификации уже зарегистрированного пользователя.

Рис.: Диаграмма последовательности, показывающая процесс аутентификации по паролю для существующих пользователей.

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

Новый пользователь

Ниже показаны диаграмма последовательности и шаги, которые объясняют, как Spotnana UI взаимодействует с сервером для аутентификации нового пользователя (или для сброса пароля существующего пользователя).

Рис.: Диаграмма последовательности, показывающая процесс аутентификации по паролю для новых пользователей.

Шаг	Процесс
Новый пользователь вводит свой email на странице входа в OBT Spotnana и нажимает Next.
1	Spotnana UI отправляет API-запрос на сервер Spotnana, чтобы получить настройки аутентификации для пользователя. В запросе передаются учетные данные пользователя. В ответе возвращаются `tmcId`, `orgId`и `authProviderType`.
1 a	Пользователь придумывает новый пароль и нажимает Next.
2	Spotnana UI отправляет API-запрос к Spotnana IdP для регистрации пользователя, передавая `clientId`, email и новый пароль. После регистрации на email пользователя отправляется одноразовый пароль (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` в заголовке запроса. Bearer token проверяется при каждом запросе к API, а ответ возвращается в Spotnana UI.

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

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

Рис.: Диаграмма последовательности, показывающая процесс аутентификации через IdP.

Шаг	Процесс
Пользователь входит через OBT или мобильное приложение Spotnana, используя свой email.
1	Spotnana UI отправляет API-запрос на сервер Spotnana, чтобы получить настройки аутентификации для пользователя. В запросе передаются учетные данные пользователя. В ответе возвращаются `tmcId`, `orgId`и `authProviderType`.
2	Spotnana UI перенаправляет запрос к Spotnana IdP.
3	Spotnana IdP перенаправляет запрос к IdP партнера. Это запускает процесс аутентификации через IdP. Примечание: При каждом перенаправлении возвращается статус 302, чтобы показать, что запрос был отправлен на другой URL.
4	Устанавливается соединение между Spotnana 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, `orgId`и `tmcId` в заголовке запроса. Bearer token проверяется при каждом запросе к API, а ответ возвращается в Spotnana UI.

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

Партнеры, которые используют API Spotnana для подключения к платформе, могут получить bearer token для своих пользователей через специальную конечную точку аутентификации. Ниже показана диаграмма последовательности для такого сценария.

Рис.: Диаграмма последовательности, показывающая процесс аутентификации через API.

Шаг Процесс

Шаг	Процесс
1	Пользователь API делает POST запрос к `get-auth-token(clientId,clientSecret)` на сервер Spotnana, чтобы получить временный bearer token. Вот пример запроса 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 token пользователю API в виде JSON-ответа.

Пользователь API делает POST запрос к get-auth-token(clientId,clientSecret) на сервер Spotnana, чтобы получить временный bearer token.

Вот пример запроса 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 token пользователю API в виде JSON-ответа.

После получения bearer token все следующие запросы к API Spotnana (например, к Trip APIs) должны содержать этот токен в заголовке для авторизации.

Примечание: Конечная точка get-auth-token(clientId, clientSecret) ограничена 100 запросами за 5 минут.

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

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

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

Ниже показана диаграмма последовательности, как происходит обмен токенами между Spotnana и серверами партнера.

Рис.: Диаграмма последовательности, показывающая аутентификацию через iFrame с обменом токенами.

Шаг	Процесс
Caller входит через интерфейс партнера.
1	Партнерский UI отображает Spotnana UI во встроенном iFrame.
2	Spotnana UI отправляет запрос в UI партнера через post message, чтобы получить токены. В запросе указывается `type=TOKEN_EXCHANGE_REQUEST`.
3	Партнерский UI отправляет API-запрос на сервер партнера, чтобы получить OAuth-токен и запустить следующий этап аутентификации.
3 a	Сервер партнера обращается к серверу Spotnana, передавая учетные данные пользователя и токен субъекта. Spotnana проверяет, что запрос отправлен от API/машинного пользователя.
3 b	Сервер Spotnana обращается к серверу партнера, чтобы получить email субъекта (caller). Email возвращается на сервер Spotnana, чтобы идентифицировать пользователя.
3 c	Ответ на API-запрос с шага 1 сервер Spotnana отправляет серверу партнера, передавая access token и refresh token. Эти данные затем передаются в UI партнера.
4	Партнерский UI отправляет токен в Spotnana UI через post message с `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI отправляет API-запрос на сервер Spotnana для генерации и получения нового bearer token. Сервер Spotnana создает bearer token и возвращает его в Spotnana UI. Примечание: Успешное создание bearer token означает, что пользователь прошёл аутентификацию и может пользоваться Spotnana.
6	После успешной аутентификации на шаге 3 все последующие API-запросы должны содержать bearer token, `orgId`и `tmcId` в заголовке запроса. Bearer token проверяется при каждом запросе к API, а ответ возвращается в Spotnana UI.

Аутентификация по коду авторизации

Ниже показана диаграмма последовательности, как происходит аутентификация с помощью кода авторизации.

Рис.: Диаграмма последовательности, показывающая аутентификацию по коду авторизации.

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

Примечание: Этот способ аутентификации не подходит, если администратор TMC разрешает нескольким пользователям входить под одним email.

Аутентификация «машина-машина» (M2M)

M2M-аутентификация подходит, если клиентское приложение обращается к стороннему callback URL для генерации accessToken для пользователя. Ниже показана диаграмма последовательности для этого сценария.

Рис.: Диаграмма последовательности, показывающая процесс M2M-аутентификации.

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