Przegląd metod uwierzytelniania w Spotnana

Utworzone przez Ashish Chaudhary, Zmodyfikowano dnia nie, 5 Paź o 2:18 RANO wg Ashish Chaudhary

Przepływy uwierzytelniania Spotnana – przegląd

SPIS TREŚCI

Przepływy uwierzytelniania Spotnana – przegląd
- Główne elementy
- Obsługiwane metody uwierzytelniania

Spotnana udostępnia różne metody uwierzytelniania, które pozwalają partnerom bezpiecznie zintegrować się z naszą platformą. W tej dokumentacji znajdą Państwo przegląd wszystkich obecnie obsługiwanych przez Spotnana sposobów uwierzytelniania wraz ze szczegółowym opisem ich działania. Przedstawione tu przepływy pokazują, jak Spotnana uwierzytelnia i autoryzuje użytkowników, aby mogli uzyskać dostęp do chronionych zasobów organizacji (czyli zasobów należących do firmy użytkownika na platformie Spotnana).

Główne elementy

Zanim rozpoczną Państwo pracę, prosimy zapoznać się z poniższą listą najważniejszych komponentów systemu, do których odwołujemy się w tej dokumentacji.

Interfejs użytkownika Spotnana (Spotnana UI)(Spotnana User Interface) Dotyczy webowej aplikacji frontendowej Spotnana (czyli narzędzia do rezerwacji online) lub aplikacji mobilnej Spotnana. W szczególności chodzi o stronę logowania, która uruchamia proces uwierzytelniania po zalogowaniu się lub utworzeniu nowego konta przez użytkownika.
Serwer Spotnana Odnosi się do backendowego serwera Spotnana, który służy do uwierzytelniania (np. autoryzacji dostępu użytkownika do zasobu oraz bezpiecznego przechowywania i przetwarzania jego danych).
Interfejs użytkownika partnera (Partner UI) (Partner's User Interface) Interfejs użytkownika (czyli aplikacja frontendowa), z którego partnerzy korzystają, aby uzyskać dostęp do platformy Spotnana. Przykładowo, w przypadku uwierzytelniania przez iFrame, platforma Spotnana jest osadzona w interfejsie partnera i użytkownicy korzystają z niej właśnie przez ten interfejs.
Serwer partnera Odnosi się do jednego lub kilku serwerów backendowych partnera, które służą do integracji z platformą Spotnana.
Spotnana IdP (Spotnana Identity Provider) Wewnętrzna usługa Spotnana, która odpowiada za zarządzanie tożsamością użytkowników i autoryzację.
IdP partnera Zewnętrzni dostawcy tożsamości (IdP) wykorzystywani przez partnerów. Przykładami takich dostawców są Google czy Azure.
OBT Narzędzie do rezerwacji online Spotnana (OBT), dostępne pod adresem https://app.spotnana.com/
Token użytkownika (subject token) W przypadku uwierzytelniania przez iFrame (lub wymianę tokenów), token użytkownika identyfikuje daną osobę. Na jego podstawie pobierane są informacje o użytkowniku i przyznawany dostęp do platformy Spotnana.
Token dostępu (access token) Uprawnienie (OAuth), które aplikacja partnera wykorzystuje do uzyskania dostępu do chronionych zasobów w imieniu użytkownika. Jest to tymczasowy klucz autoryzacyjny, pozwalający na wykonywanie zapytań do API bez ujawniania danych logowania użytkownika.
Token odświeżania (refresh token) Długoterminowe uprawnienie, które pozwala uzyskać nowy token dostępu bez konieczności ponownego logowania się użytkownika. Zazwyczaj jest wydawany razem z tokenem dostępu podczas pierwszego logowania.
Dane klienta (client credentials) Dane przekazywane użytkownikom, którzy łączą się bezpośrednio z API Spotnana (czyli unikalny clientId oraz clientSecret).
PID (identyfikator osobisty) Unikalny identyfikator przypisany użytkownikowi. PID służy do pobierania informacji o użytkowniku z serwera Spotnana.
orgId Unikalny identyfikator organizacji użytkownika nadawany przez Spotnana.
tmcId Unikalny identyfikator przypisany przez Spotnana dla firmy zarządzającej podróżami (TMC – Travel Management Company).

Obsługiwane metody uwierzytelniania

Poniżej przedstawiamy metody uwierzytelniania obsługiwane przez Spotnana:

Uwierzytelnianie hasłem
- Użytkownik istniejący
- Nowy użytkownik
Uwierzytelnianie przez IdP
Uwierzytelnianie przez API
Uwierzytelnianie przez iFrame
Uwierzytelnianie na podstawie kodu autoryzacyjnego
Uwierzytelnianie typu maszyna-maszyna (M2M)

Uwierzytelnianie hasłem

W przypadku uwierzytelniania hasłem, interfejs Spotnana (czyli strona logowania lub rejestracji w OBT) inicjuje i obsługuje proces uwierzytelniania z serwerami backendowymi Spotnana. W zależności od tego, czy użytkownik loguje się na istniejące konto, czy zakłada nowe, proces ten przebiega nieco inaczej. Oba te scenariusze zostały szczegółowo opisane poniżej wraz ze schematami.

Użytkownik istniejący

Poniższy diagram oraz opisane kroki pokazują, jak interfejs Spotnana współpracuje z usługami backendowymi podczas uwierzytelniania istniejącego użytkownika.

Rys.: Diagram sekwencji ilustrujący uwierzytelnianie hasłem dla istniejących użytkowników.

Krok	Przebieg
Użytkownik, który już posiada konto, loguje się przez OBT lub aplikację mobilną Spotnana, podając swój adres e-mail.
1	Interfejs Spotnana wysyła zapytanie API do serwera Spotnana, aby pobrać konfigurację uwierzytelniania dla użytkownika. W zapytaniu przekazywane są dane logowania użytkownika. W odpowiedzi zwracane są wartości: `tmcId`, `orgId`, oraz `authProviderType`.
2	Interfejs Spotnana wysyła zapytanie API do Spotnana IdP, przekazując `clientId`, adres e-mail oraz hasło. Spotnana IdP generuje nowy token typu bearer i zwraca go do interfejsu Spotnana. Na tym etapie użytkownik zostaje uwierzytelniony.
3	Po pomyślnym uwierzytelnieniu w kroku 2, każde kolejne zapytanie API musi zawierać token bearer, a także `orgId`, oraz `tmcId` w nagłówku żądania. Token bearer jest weryfikowany przy każdym zapytaniu API, a odpowiedź zwracana jest do interfejsu Spotnana.

Nowy użytkownik

Poniższy diagram oraz opisane kroki pokazują, jak interfejs Spotnana współpracuje z usługami backendowymi podczas uwierzytelniania nowego użytkownika (lub użytkownika, który chce zresetować hasło).

Rys.: Diagram sekwencji ilustrujący uwierzytelnianie hasłem dla nowych użytkowników.

Krok	Przebieg
Nowy użytkownik wpisuje swój adres e-mail na stronie logowania OBT Spotnana i klika Dalej.
1	Interfejs Spotnana wysyła zapytanie API do serwera Spotnana, aby pobrać konfigurację uwierzytelniania dla użytkownika. W zapytaniu przekazywane są dane logowania użytkownika. W odpowiedzi zwracane są wartości: `tmcId`, `orgId`, oraz `authProviderType`.
1 a	Użytkownik ustawia nowe hasło i klika Dalej.
2	Interfejs Spotnana wysyła zapytanie API do Spotnana IdP w celu rejestracji użytkownika, przekazując `clientId`, adres e-mail oraz nowe hasło. Po zarejestrowaniu danych, na adres e-mail użytkownika wysyłane jest jednorazowe hasło (OTP).
3	Użytkownik wpisuje kod OTP w interfejsie Spotnana i klika Zweryfikuj. Interfejs Spotnana wysyła żądanie do Spotnana IdP w celu weryfikacji OTP i wygenerowania tokenu bearer do logowania. Token bearer zostaje wygenerowany i przekazany do interfejsu Spotnana. Oznacza to, że użytkownik został pomyślnie uwierzytelniony i może korzystać z platformy Spotnana na podstawie tego tokenu.
4	Po pomyślnej autoryzacji w kroku 3, każde kolejne zapytanie API musi zawierać token bearer, a także `orgId`, oraz `tmcId` w nagłówku żądania. Token bearer jest weryfikowany przy każdym zapytaniu API, a odpowiedź zwracana jest do interfejsu Spotnana.

Uwierzytelnianie przez IdP

Spotnana umożliwia uwierzytelnianie przez IdP, takie jak Google, Azure oraz dostawców własnych, korzystających z OpenID Connect lub SAML. Poniżej opisano przebieg uwierzytelniania przez IdP na diagramie i w krokach.

Rys.: Diagram sekwencji ilustrujący przebieg uwierzytelniania przez IdP.

Krok	Przebieg
Użytkownik loguje się przez OBT lub aplikację mobilną Spotnana, podając swój adres e-mail.
1	Interfejs Spotnana wysyła zapytanie API do serwera Spotnana, aby pobrać konfigurację uwierzytelniania dla użytkownika. W zapytaniu przekazywane są dane logowania użytkownika. W odpowiedzi zwracane są wartości: `tmcId`, `orgId`, oraz `authProviderType`.
2	Interfejs Spotnana przekierowuje żądanie do Spotnana IdP.
3	Spotnana IdP przekierowuje żądanie do IdP partnera. W ten sposób rozpoczyna się proces uwierzytelniania przez IdP. Uwaga: Przy każdym przekierowaniu zwracany jest kod statusu 302, co oznacza przekierowanie na inny adres URL.
4	Nawiązywane jest połączenie pomiędzy Spotnana IdP a IdP partnera, aby potwierdzić uwierzytelnienie użytkownika przez IdP partnera. Uwaga: W trakcie tego połączenia Spotnana IdP przesyła `clientId` i `clientSecret` jako dane zakodowane w formacie URL w wywołaniu API do IdP partnera. Jeśli serwery IdP nie obsługują tego formatu, serwer Spotnana może pośredniczyć i przetłumaczyć dane na format akceptowany przez IdP partnera.
5	IdP partnera pomyślnie uwierzytelnia użytkownika. Uwaga: Po tym kroku profil użytkownika musi zostać jeszcze zweryfikowany przez token bearer.
5 a	Po pomyślnym uwierzytelnieniu odpowiedź z IdP partnera trafia do Spotnana IdP.
5 b	Spotnana IdP generuje unikalny kod dla profilu użytkownika i przekazuje go do interfejsu Spotnana.
6	Interfejs Spotnana wysyła zapytanie API do Spotnana IdP, przekazując `clientID` oraz kod otrzymany w kroku 5(b). Spotnana IdP generuje nowy token bearer i przekazuje go do interfejsu Spotnana. Uwaga: Pomyślne utworzenie tokenu bearer oznacza, że użytkownik został uwierzytelniony i może korzystać z platformy Spotnana.
7	Po autoryzacji w kroku 6, każde kolejne zapytanie API musi zawierać token bearer, a także `orgId`, oraz `tmcId` w nagłówku żądania. Token bearer jest weryfikowany przy każdym zapytaniu API, a odpowiedź zwracana jest do interfejsu Spotnana.

Uwierzytelnianie przez API

Partnerzy korzystający z API Spotnana mogą użyć naszego endpointu uwierzytelniającego, aby wygenerować token bearer dla swoich użytkowników. Poniższy diagram pokazuje, jak wygląda ten proces krok po kroku.

Rys.: Diagram sekwencji ilustrujący uwierzytelnianie przez API.

Krok Przebieg

Krok	Przebieg
1	Użytkownik API wykonuje wywołanie POST do endpointu `get-auth-token(clientId,clientSecret)` na serwerze Spotnana, aby wygenerować i pobrać tymczasowy token bearer. Poniżej znajduje się przykładowe wywołanie cUrl, z którego można skorzystać przy wywołaniu endpointu `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>" }' Uwaga: Wartości `clientId` i `clientSecret` należy zastąpić danymi, które otrzymali Państwo od Spotnana.
2	Serwer Spotnana wywołuje metodę `getToken(clientId,clientSecret)` w Spotnana IdP, która generuje tymczasowy `bearerToken` i zwraca go do serwera Spotnana. Serwer Spotnana przekazuje ten token bearer w odpowiedzi JSON do użytkownika API.

Użytkownik API wykonuje wywołanie POST do endpointu get-auth-token(clientId,clientSecret) na serwerze Spotnana, aby wygenerować i pobrać tymczasowy token bearer.

Poniżej znajduje się przykładowe wywołanie cUrl, z którego można skorzystać przy wywołaniu endpointu 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>"
}'

Uwaga: Wartości clientId i clientSecret należy zastąpić danymi, które otrzymali Państwo od Spotnana.

Serwer Spotnana wywołuje metodę getToken(clientId,clientSecret) w Spotnana IdP, która generuje tymczasowy bearerToken i zwraca go do serwera Spotnana.
Serwer Spotnana przekazuje ten token bearer w odpowiedzi JSON do użytkownika API.

Gdy użytkownik API otrzyma token bearer, każde kolejne zapytanie do API Spotnana (np. Trip APIs) musi zawierać token bearer w nagłówku autoryzacyjnym.

Uwaga: Endpoint get-auth-token(clientId, clientSecret) jest ograniczony do 100 wywołań API na 5 minut.

Uwierzytelnianie przez iFrame

iFrame lub rozwiązanie osadzone polega na tym, że partnerzy umieszczają interfejs Spotnana w swoim własnym interfejsie, dzięki czemu użytkownicy korzystają z platformy Spotnana przez UI partnera. W tym przypadku uwierzytelnianie użytkownika opiera się na wymianie tokenów pomiędzy systemami partnera i Spotnana.

Uwaga: W przypadku uwierzytelniania przez iFrame użytkownik logujący się będzie nazywany caller. Pozwala to obsłużyć sytuacje, w których użytkownik API/maszyny loguje się i żąda tokenu dostępu dla innej osoby. Taki użytkownik API/maszyny może użyć danych administratora TMC (Travel Management Company), aby połączyć się bezpośrednio z serwerem Spotnana. Dlatego będziemy używać określenia caller jako ogólnego terminu, który może oznaczać zarówno użytkownika logującego się na własny profil, jak i użytkownika API/maszyny żądającego tokenu dostępu dla innej osoby.

Poniższy diagram sekwencji pokazuje, jak przebiega uwierzytelnianie przez wymianę tokenów pomiędzy serwerami Spotnana i partnera.

Rys.: Diagram sekwencji ilustrujący uwierzytelnianie przez iFrame z użyciem wymiany tokenów.

Krok	Przebieg
Caller loguje się przez interfejs partnera (Partner UI).
1	Partner UI wyświetla interfejs Spotnana za pomocą iFrame.
2	Interfejs Spotnana wysyła do Partner UI żądanie przez post message w celu pobrania tokenów. W żądaniu ustawiony jest parametr `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI wysyła zapytanie API do serwera partnera, aby pobrać token OAuth, co inicjuje kolejne kroki procesu uwierzytelniania.
3 a	Serwer partnera wywołuje serwer Spotnana, przekazując dane użytkownika i token użytkownika (subject token). Serwer Spotnana sprawdza, czy żądanie pochodzi od użytkownika API/maszyny.
3 b	Serwer Spotnana wywołuje serwer partnera, aby pobrać adres e-mail użytkownika (caller). E-mail jest pobierany i zwracany do serwera Spotnana, który identyfikuje użytkownika na tej podstawie.
3 c	Odpowiedź na zapytanie API z kroku 1 jest przekazywana przez serwer Spotnana do serwera partnera i zawiera token dostępu oraz token odświeżania. Następnie te dane są przekazywane do Partner UI.
4	Partner UI przekazuje token do interfejsu Spotnana przez post message z parametrem `type=TOKEN_EXCHANGE_RESPONSE.`
5	Interfejs Spotnana wysyła zapytanie API do serwera Spotnana o wygenerowanie i zwrócenie nowego tokenu bearer. Serwer Spotnana generuje token bearer i zwraca go do interfejsu Spotnana. Uwaga: Pomyślne utworzenie tokenu bearer oznacza, że użytkownik został uwierzytelniony i może korzystać z platformy Spotnana.
6	Po autoryzacji użytkownika w kroku 3, każde kolejne zapytanie API musi zawierać token bearer, a także `orgId`, oraz `tmcId` w nagłówku żądania. Token bearer jest weryfikowany przy każdym zapytaniu API, a odpowiedź zwracana jest do interfejsu Spotnana.

Uwierzytelnianie na podstawie kodu autoryzacyjnego

Poniższy diagram sekwencji pokazuje, jak przebiega uwierzytelnianie z użyciem kodu autoryzacyjnego.

Rys.: Diagram sekwencji ilustrujący uwierzytelnianie na podstawie kodu autoryzacyjnego.

Krok	Przebieg
1	Partner UI wywołuje serwer partnera, aby pobrać kod autoryzacyjny dla caller logującego się. Kod autoryzacyjny jest pobierany i przekazywany do Partner UI.
2	Partner UI wysyła żądanie do interfejsu Spotnana z wykorzystaniem niestandardowego adresu przekierowania, zawierającego `tmcId` oraz `authCode` jako parametry.
3	Interfejs Spotnana wykonuje wywołanie API typu POST do serwera Spotnana, korzystając z endpointu `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	Serwer Spotnana wysyła żądanie do serwera partnera, aby pobrać `pid` użytkownika na podstawie kodu autoryzacyjnego. PID użytkownika `jest pobierany i przekazywany do serwera Spotnana.` .
3 b	Serwer Spotnana generuje token dostępu oraz token odświeżania i przekazuje je do interfejsu Spotnana.
4	Interfejs Spotnana wysyła żądanie do serwera Spotnana, przekazując token dostępu oraz token odświeżania, aby wygenerować i pobrać token bearer. Token bearer zostaje wygenerowany i przekazany do interfejsu Spotnana. Uwaga: Pomyślne utworzenie tokenu bearer oznacza, że użytkownik został uwierzytelniony i może korzystać z platformy Spotnana.
5	Po autoryzacji użytkownika w kroku 4, każde kolejne zapytanie API musi zawierać token bearer, a także `orgId`, oraz `tmcId` w nagłówku żądania. Token bearer jest weryfikowany przy każdym zapytaniu API, a odpowiedź zwracana jest do interfejsu Spotnana.

Uwaga: Tego typu uwierzytelniania nie można stosować w przypadku, gdy administrator TMC umożliwia logowanie kilku użytkownikom na ten sam adres e-mail.

Uwierzytelnianie typu maszyna-maszyna (M2M)

Metoda uwierzytelniania M2M sprawdzi się, gdy aplikacja kliencka musi uzyskać dostęp do zewnętrznego adresu callback w celu wygenerowania accessToken dla użytkownika. Poniższy diagram sekwencji ilustruje przebieg uwierzytelniania M2M.

Rys.: Diagram sekwencji ilustrujący przebieg uwierzytelniania M2M.

Krok	Przebieg
Klucze publiczne wszystkich aplikacji biorących udział w uwierzytelnianiu są synchronizowane pomiędzy serwerem Spotnana a Spotnana IdP. Będą one później wykorzystywane do weryfikacji tokenu dostępu podczas uwierzytelniania.
1	Serwer partnera wysyła żądanie API do `/oauth2/token(clientId,clientSecret)` w Spotnana IdP, aby wygenerować token bearer. Nowy token bearer jest zwracany do serwera partnera.
2	Serwer partnera wysyła żądanie API do zewnętrznego adresu callback, aby wygenerować token dostępu dla użytkownika. Token dostępu jest tworzony i przekazywany do serwera Spotnana.
3	Serwer Spotnana weryfikuje podpis tokenu dostępu przy użyciu wcześniej zsynchronizowanych kluczy publicznych. Sprawdza również `claim_id` który potwierdza tożsamość partnera. Następnie token dostępu jest przekazywany do serwera partnera w celu uwierzytelnienia użytkownika.