Přehled způsobů ověřování ve Spotnaně

Vytvořil(a) Ashish Chaudhary, Změněno dne So, 4 Říjen v 10:17 ODPOLEDNE dle Ashish Chaudhary

Přehled autentizačních postupů ve Spotnana

OBSAH

Přehled autentizačních postupů ve Spotnana
- Hlavní komponenty
- Podporované způsoby ověřování

Spotnana nabízí několik způsobů ověřování, které umožňují partnerům bezpečně integrovat jejich systémy s naší platformou. V této dokumentaci najdete přehled všech aktuálně podporovaných autentizačních metod a podrobné vysvětlení jejich průběhu. Jednotlivé autentizační toky zde ukazují, jak Spotnana ověřuje a autorizuje uživatele pro přístup ke chráněným firemním zdrojům (tedy zdrojům, které patří společnosti uživatele na platformě Spotnana).

Hlavní komponenty

Než začnete, projděte si tento seznam základních systémových komponent, na které se v dokumentaci odkazujeme.

Spotnana UI(Uživatelské rozhraní Spotnana) Jedná se o webovou aplikaci Spotnana (tzv. Online Booking Tool) nebo mobilní aplikaci Spotnana. Konkrétně jde o přihlašovací stránku, která spouští autentizační proces na straně uživatele při přihlášení nebo při vytváření nového účtu.
Spotnana server Zadní (backend) server Spotnana, který slouží k ověřování uživatelů (například k autorizaci přístupu ke zdrojům a bezpečnému ukládání a zpracování uživatelských údajů).
Partner UI (Uživatelské rozhraní partnera) Frontendová aplikace, kterou partneři používají pro přístup na platformu Spotnana. Například při ověřování pomocí iFrame je Spotnana vložena do rozhraní partnera a uživatelé přistupují ke Spotnana právě přes toto rozhraní.
Partner server Jeden nebo více backendových serverů partnera, které slouží k integraci se Spotnana.
Spotnana IdP (Poskytovatel identity Spotnana) Vnitřní služba Spotnana pro správu uživatelských identit a autorizaci.
Partner IdP Externí poskytovatelé identity (IdP), které využívají partneři. Mezi běžné patří například Google nebo Azure.
OBT Online Booking Tool (OBT) od Spotnana, dostupný na adrese https://app.spotnana.com/
Předmětový token (subject token) Při ověřování přes iFrame (nebo při výměně tokenů) představuje subject token identitu uživatele. Tento token slouží k vyhledání uživatelských údajů a k autorizaci přístupu na platformu Spotnana.
Přístupový token (access token) Ověřovací údaj (OAuth), který partnerova aplikace používá k přístupu ke chráněným zdrojům jménem uživatele. Jde o dočasný autorizační klíč, díky kterému lze volat API bez nutnosti sdílet uživatelské heslo.
Obnovovací token (refresh token) Dlouhodobý ověřovací údaj, který umožňuje získat nový přístupový token bez opětovného přihlášení uživatele. Obvykle je vydán společně s access tokenem při prvním přihlášení.
Přihlašovací údaje klienta (client credentials) Údaje poskytnuté uživatelům, kteří se připojují přímo k API Spotnana (tedy jedinečné clientId a clientSecret).
PID (osobní identifikátor) Jedinečný identifikátor vytvořený pro uživatele. PID slouží k načtení uživatelských údajů ze serveru Spotnana.
orgId Jedinečný identifikátor, který Spotnana přiřadí organizaci uživatele.
tmcId Jedinečný identifikátor, který Spotnana přiřadí TMC (Travel Management Company).

Podporované způsoby ověřování

Následující způsoby ověřování jsou ve Spotnana podporovány:

Ověřování pomocí hesla
- Stávající uživatel
- Nový uživatel
Ověřování přes poskytovatele identity (IdP)
Ověřování pomocí API
Ověřování pomocí iFrame
Ověřování pomocí autorizačního kódu
Ověřování stroj–stroj (M2M)

Ověřování pomocí hesla

Při ověřování pomocí hesla spouští a řídí autentizační proces rozhraní Spotnana UI (tj. přihlašovací nebo registrační stránka v OBT) ve spolupráci se servery Spotnana. Tento způsob má dvě varianty podle toho, zda se uživatel přihlašuje ke stávajícímu účtu, nebo si vytváří nový. Obě varianty jsou níže popsány včetně sekvenčních diagramů.

Stávající uživatel

Následující diagram a kroky vysvětlují, jak Spotnana UI spolupracuje s backendovými službami při ověřování stávajícího uživatele.

Obr.: Sekvenční diagram znázorňující ověřování pomocí hesla pro stávající uživatele.

Krok	Průběh
Stávající uživatel se přihlásí do OBT nebo mobilní aplikace Spotnana pomocí své e-mailové adresy.
1	Spotnana UI odešle API požadavek na server Spotnana pro získání informací o nastavení ověřování uživatele. V požadavku jsou předány přihlašovací údaje uživatele. Odpověď obsahuje hodnoty `tmcId`, `orgId`a `authProviderType`.
2	Spotnana UI odešle API požadavek na Spotnana IdP s údaji `clientId`, e-mailem a heslem. Spotnana IdP vygeneruje nový bearer token a vrátí jej Spotnana UI. Tímto krokem je uživatel ověřen.
3	Po úspěšném ověření v kroku 2 musí být ve všech dalších API požadavcích uveden bearer token, `orgId`a `tmcId` v hlavičce požadavku. Bearer token je ověřován u všech příchozích API požadavků a odpověď je zaslána zpět do Spotnana UI.

Nový uživatel

Následující diagram a kroky vysvětlují, jak Spotnana UI spolupracuje s backendovými službami při ověřování nového uživatele (nebo uživatele, který si resetuje heslo).

Obr.: Sekvenční diagram znázorňující ověřování pomocí hesla pro nové uživatele.

Krok	Průběh
Nový uživatel zadá svou e-mailovou adresu na přihlašovací stránce Spotnana OBT a klikne na Další.
1	Spotnana UI odešle API požadavek na server Spotnana pro získání informací o nastavení ověřování uživatele. V požadavku jsou předány přihlašovací údaje uživatele. Odpověď obsahuje hodnoty `tmcId`, `orgId`a `authProviderType`.
1 a	Uživatel zadá nové heslo a klikne na Další.
2	Spotnana UI odešle API požadavek na Spotnana IdP pro registraci uživatele spolu s jeho `clientId`, e-mailem a novým heslem. Po registraci údajů je uživateli na e-mail zasláno jednorázové heslo (OTP).
3	Uživatel zadá OTP v rozhraní Spotnana UI a klikne na Ověřit. Spotnana UI odešle požadavek na Spotnana IdP pro ověření OTP a vygenerování bearer tokenu pro přihlášení. Bearer token je vygenerován a vrácen Spotnana UI. Tím je uživatel úspěšně ověřen a může používat platformu Spotnana s tímto tokenem.
4	Po ověření uživatele v kroku 3 musí být ve všech dalších API požadavcích uveden bearer token, `orgId`a `tmcId` v hlavičce požadavku. Bearer token je ověřován u všech příchozích API požadavků a odpověď je zaslána zpět do Spotnana UI.

Ověřování přes poskytovatele identity (IdP)

Spotnana umožňuje ověřování přes IdP jako Google, Azure nebo vlastní IdP pomocí OpenID Connect i SAML protokolu. Následující diagram a kroky znázorňují průběh ověřování přes IdP.

Obr.: Sekvenční diagram znázorňující ověřování přes IdP.

Krok	Průběh
Uživatel se přihlásí do OBT nebo mobilní aplikace Spotnana pomocí své e-mailové adresy.
1	Spotnana UI odešle API požadavek na server Spotnana pro získání informací o nastavení ověřování uživatele. V požadavku jsou předány přihlašovací údaje uživatele. Odpověď obsahuje hodnoty `tmcId`, `orgId`a `authProviderType`.
2	Spotnana UI přesměruje požadavek na Spotnana IdP.
3	Spotnana IdP přesměruje požadavek na IdP partnera. Tím se spustí ověřování uživatele přes IdP. Poznámka: Při každém přesměrování je vrácen kód 302, který značí přesun požadavku na jinou adresu.
4	Mezi Spotnana IdP a IdP partnera se naváže spojení, aby bylo možné ověřit uživatele přes IdP partnera. Poznámka: Během tohoto spojení Spotnana IdP předává `clientId` a `clientSecret` jako data ve formátu URL-encoded v rámci API volání na IdP partnera. Pokud IdP partnera tento formát nezpracuje, může server Spotnana fungovat jako prostředník a převést data do vhodného formátu.
5	IdP partnera úspěšně ověří uživatele. Poznámka: Po tomto kroku je třeba ještě ověřit profil uživatele pomocí bearer tokenu.
5 a	Po úspěšném ověření je odpověď z IdP partnera zaslána Spotnana IdP.
5 b	Spotnana IdP vygeneruje pro uživatelský profil jedinečný kód a pošle jej Spotnana UI.
6	Spotnana UI odešle API požadavek na Spotnana IdP s `clientID` a kódem získaným v kroku 5(b). Spotnana IdP vygeneruje nový bearer token a pošle jej Spotnana UI. Poznámka: Vygenerování bearer tokenu znamená, že uživatel byl úspěšně ověřen a má přístup ke Spotnana.
7	Po ověření uživatele v kroku 6 musí být ve všech dalších API požadavcích uveden bearer token, `orgId`a `tmcId` v hlavičce požadavku. Bearer token je ověřován u všech příchozích API požadavků a odpověď je zaslána zpět do Spotnana UI.

Ověřování pomocí API

Partneři, kteří využívají API Spotnana pro propojení se systémem, mohou použít náš autentizační endpoint pro vygenerování bearer tokenu pro své uživatele. Následující sekvenční diagram ukazuje průběh ověřování při použití API.

Obr.: Sekvenční diagram znázorňující ověřování pomocí API.

Krok Průběh

Krok	Průběh
1	Uživatel API provede volání POST na endpoint `get-auth-token(clientId,clientSecret)` na serveru Spotnana, aby získal dočasný bearer token. Zde je ukázka cURL požadavku, který můžete použít při volání 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>" }' Poznámka: Zaměňte hodnoty `clientId` a `clientSecret` za přihlašovací údaje, které jste obdrželi od Spotnana.
2	Server Spotnana zavolá metodu `getToken(clientId,clientSecret)` ve Spotnana IdP, která vygeneruje dočasný `bearerToken` a pošle jej zpět serveru Spotnana. Server Spotnana odešle tento bearer token jako JSON odpověď uživateli API.

Uživatel API provede volání POST na endpoint get-auth-token(clientId,clientSecret) na serveru Spotnana, aby získal dočasný bearer token.

Zde je ukázka cURL požadavku, který můžete použít při volání 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>"
}'

Poznámka: Zaměňte hodnoty clientId a clientSecret za přihlašovací údaje, které jste obdrželi od Spotnana.

Server Spotnana zavolá metodu getToken(clientId,clientSecret) ve Spotnana IdP, která vygeneruje dočasný bearerToken a pošle jej zpět serveru Spotnana.
Server Spotnana odešle tento bearer token jako JSON odpověď uživateli API.

Jakmile uživatel API získá bearer token, musí jej uvádět v hlavičce všech dalších požadavků na Spotnana API (například Trip API).

Poznámka: Endpoint get-auth-token(clientId, clientSecret) je omezen na 100 volání API za 5 minut.

Ověřování pomocí iFrame

iFrame nebo vložené řešení znamená, že partneři vloží Spotnana UI do svého rozhraní. Uživatelé tak přistupují ke Spotnana přes rozhraní partnera. V tomto scénáři probíhá ověření uživatele na základě výměny tokenů mezi systémy partnera a Spotnana.

Poznámka: Při ověřování pomocí iFrame označujeme uživatele, který se přihlašuje, jako volajícího (caller). Toto označení umožňuje popsat situace, kdy se přihlašuje API/strojový uživatel a žádá přístupový token pro jiného uživatele. Takový API/strojový uživatel může použít například administrátorské údaje TMC pro přímé spojení se serverem Spotnana. Proto používáme termín volající (caller) jako obecné označení, které může znamenat buď uživatele přihlašujícího se ke svému profilu, nebo API/strojového uživatele žádajícího token pro jiného uživatele.

Následující sekvenční diagram ukazuje, jak probíhá autentizační tok pomocí výměny tokenů mezi Spotnana a servery partnera.

Obr.: Sekvenční diagram znázorňující ověřování pomocí iFrame a výměny tokenů.

Krok	Průběh
Volající se přihlásí přes Partner UI.
1	Partner UI zobrazí Spotnana UI pomocí iFrame.
2	Spotnana UI odešle požadavek na Partner UI prostřednictvím post message pro získání tokenů. Požadavek obsahuje `type=TOKEN_EXCHANGE_REQUEST`.
3	Partner UI odešle API požadavek na server partnera pro získání OAuth tokenu a tím zahájí další kroky autentizačního procesu.
3 a	Server partnera zavolá server Spotnana s uživatelskými údaji a subject tokenem. Server Spotnana ověří, zda požadavek poslal API/strojový uživatel.
3 b	Server Spotnana zavolá server partnera pro získání e-mailu subjektu (tj. volajícího). E-mail je získán a vrácen serveru Spotnana, který jej použije k identifikaci uživatele.
3 c	Odpověď na API požadavek z kroku 1 je odeslána serverem Spotnana zpět na server partnera a obsahuje access token a refresh token. Tyto údaje jsou následně předány Partner UI.
4	Partner UI odešle token Spotnana UI pomocí post message s `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI odešle API požadavek na server Spotnana pro vygenerování a získání nového bearer tokenu. Server Spotnana vygeneruje bearer token a vrátí jej Spotnana UI. Poznámka: Vygenerování bearer tokenu znamená, že uživatel byl úspěšně ověřen a má přístup ke Spotnana.
6	Po ověření uživatele ve 3. kroku musí být ve všech dalších API požadavcích uveden bearer token, `orgId`a `tmcId` v hlavičce požadavku. Bearer token je ověřován u všech příchozích API požadavků a odpověď je zaslána zpět do Spotnana UI.

Ověřování pomocí autorizačního kódu

Následující sekvenční diagram ukazuje, jak probíhá autentizační tok pomocí autorizačního kódu.

Obr.: Sekvenční diagram znázorňující ověřování pomocí autorizačního kódu.

Krok	Průběh
1	Partner UI zavolá server partnera pro získání autorizačního kódu pro přihlašujícího se volajícího. Autorizační kód je získán a vrácen Partner UI.
2	Partner UI odešle požadavek na Spotnana UI pomocí vlastní přesměrovací URL, která obsahuje `tmcId` a `authCode` jako parametry.
3	Spotnana UI provede POST API volání na server Spotnana pomocí endpointu `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	Server Spotnana odešle požadavek na server partnera pro získání uživatelského `pid` pomocí autorizačního kódu. Uživatelský `pid` je získán a předán serveru Spotnana.
3 b	Access token a refresh token jsou vygenerovány serverem Spotnana a zaslány Spotnana UI.
4	Spotnana UI odešle požadavek na server Spotnana s access tokenem a refresh tokenem pro vygenerování a získání bearer tokenu pro přístup. Bearer token je vygenerován a zaslán Spotnana UI. Poznámka: Vygenerování bearer tokenu znamená, že uživatel byl úspěšně ověřen a má přístup ke Spotnana.
5	Po ověření uživatele ve 4. kroku musí být ve všech dalších API požadavcích uveden bearer token, `orgId`a `tmcId` v hlavičce požadavku. Bearer token je ověřován u všech příchozích API požadavků a odpověď je zaslána zpět do Spotnana UI.

Poznámka: Tento autentizační tok nelze využít v situaci, kdy administrátor TMC umožňuje více uživatelům přihlašovat se stejným e-mailem.

Ověřování stroj–stroj (M2M)

Metoda M2M je vhodná v případech, kdy klientská aplikace v rámci autentizačního procesu přistupuje na callback URL třetí strany za účelem vygenerování accessToken pro uživatele. Následující sekvenční diagram ukazuje průběh M2M autentizace.

Obr.: Sekvenční diagram znázorňující průběh M2M autentizace.

Krok	Průběh
Veškeré veřejné klíče používané v autentizaci jsou synchronizovány mezi serverem Spotnana a Spotnana IdP. Tyto klíče budou později použity k ověření access tokenu v rámci autentizačního procesu.
1	Server partnera odešle API požadavek na `/oauth2/token(clientId,clientSecret)` do Spotnana IdP pro vygenerování bearer tokenu. Nový bearer token je zaslán zpět na server partnera.
2	Server partnera odešle API požadavek na callback URL třetí strany pro vygenerování access tokenu pro uživatele. Tento access token je vytvořen a zaslán serveru Spotnana.
3	Server Spotnana ověří podpis access tokenu pomocí dříve synchronizovaných veřejných klíčů. Dále ověří hodnotu `claim_id` čímž potvrdí identitu partnera. Access token je následně předán serveru partnera pro ověření uživatele.