Översikt över Spotnanas autentiseringsflöden

Skapad av Ashish Chaudhary, Ändrad den Sön, 5 okt. vid 4:45 F.M. efter Ashish Chaudhary

Spotnanas autentiseringsflöden – Översikt

INNEHÅLLSFÖRTECKNING

Spotnanas autentiseringsflöden – Översikt
- Centrala komponenter
- Stödda autentiseringsmetoder

Spotnana erbjuder flera olika autentiseringsmetoder som gör det möjligt för partners att integrera säkert med vår plattform. I denna dokumentation får du en översikt över de autentiseringsmetoder som Spotnana stödjer, tillsammans med detaljerade beskrivningar av hur respektive flöde fungerar. De olika autentiseringsflödena visar hur Spotnana identifierar och ger användare rättigheter att komma åt skyddade resurser på organisationsnivå (det vill säga resurser som tillhör användarens företag på Spotnanas plattform).

Centrala komponenter

Läs gärna igenom denna lista med definitioner av de viktigaste systemkomponenterna som nämns i dokumentationen, innan du börjar.

Spotnana UI(Spotnanas användargränssnitt) Syftar på Spotnanas webbaserade gränssnitt (Online Booking Tool) eller Spotnanas mobilapp. Här avses framför allt inloggningssidan, som startar autentiseringsflödet när användaren loggar in eller skapar ett nytt konto.
Spotnana-server Syftar på Spotnanas backend-server som används för autentisering (till exempel för att ge användare åtkomst till resurser samt för att lagra och hantera användaruppgifter på ett säkert sätt).
Partner UI (Partnerns användargränssnitt) Det användargränssnitt (frontend-applikation) som partners använder för att komma åt Spotnanas plattform. Vid iFrame-baserad autentisering bäddas Spotnanas plattform in i partnerns gränssnitt, och användarna når Spotnana via partnerns UI.
Partner-server Syftar på en eller flera backend-servrar som våra partners använder för att integrera mot Spotnana.
Spotnana IdP (Spotnanas identitetsleverantör) Syftar på Spotnanas interna tjänst för hantering av användaridentiteter och behörigheter.
Partner IdP Tredjeparts identitetsleverantörer (IdP) som används av partners. Vanliga exempel är Google och Azure.
OBT Spotnanas Online Booking Tool (OBT), som du hittar på https://app.spotnana.com/
Subject token Vid iFrame-baserad (eller token exchange) autentisering används ett subject token för att representera användarens identitet. Denna token används för att hämta information om användaren och ge rätt behörighet till Spotnanas plattform.
Access token Ett tillfälligt behörighetsbevis (OAuth) som partnerapplikationer använder för att komma åt skyddade resurser för en användares räkning. Med denna nyckel kan applikationer göra API-anrop utan att användarens inloggningsuppgifter exponeras.
Refresh token Ett långlivat behörighetsbevis som används för att hämta nya access tokens utan att användaren behöver logga in igen. Den utfärdas vanligtvis tillsammans med access token vid första inloggningen.
Klientuppgifter Information som ges till användare som ansluter direkt till Spotnanas API:er (till exempel ett unikt clientId och clientSecret).
PID (Personlig identifierare) En personlig identifierare som skapas för användaren. PID används för att hämta användarens information från Spotnanas server.
orgId Ett unikt id som Spotnana tilldelar användarens organisation.
tmcId Ett unikt id som Spotnana tilldelar en TMC (Travel Management Company).

Stödda autentiseringsmetoder

Nedan listas de olika autentiseringsmetoder som Spotnana stödjer:

Lösenordsbaserad autentisering
- Befintlig användare
- Ny användare
IdP-baserad autentisering
API-baserad autentisering
iFrame-baserad autentisering
Autentisering med auktoriseringskod
Maskin-till-maskin (M2M) autentisering

Lösenordsbaserad autentisering

När du använder lösenordsbaserad autentisering är det Spotnana UI (alltså inloggnings- eller registreringssidan i OBT) som startar och hanterar autentiseringsprocessen mot Spotnanas backend-servrar. Flödet ser olika ut beroende på om användaren loggar in med ett befintligt konto eller registrerar sig som ny användare. Nedan beskrivs båda dessa flöden steg för steg, med tillhörande sekvensdiagram.

Befintlig användare

Diagrammet och stegen nedan visar hur Spotnana UI samarbetar med backend-tjänsterna för att autentisera en befintlig användare.

Figur: Ett sekvensdiagram som visar lösenordsbaserad autentisering för befintliga användare.

Steg	Flöde
En befintlig användare loggar in via OBT eller Spotnanas mobilapp med sin e-postadress.
1	Spotnana UI skickar en API-förfrågan till Spotnanas server för att hämta användarens autentiseringsinställningar. Förfrågan innehåller användarens inloggningsuppgifter som parametrar. Svaret innehåller användarens `tmcId`, `orgId`och `authProviderType`.
2	Spotnana UI skickar en API-förfrågan till Spotnana IdP med `clientId`, e-postadress och lösenord. Spotnana IdP skapar och returnerar en ny bearer token till Spotnana UI. I detta steg autentiseras användaren.
3	När användaren har autentiserats i steg 2 måste alla efterföljande API-anrop innehålla bearer token, `orgId`och `tmcId` i anropets header. Bearertoken verifieras i samtliga inkommande API-anrop och svaret skickas tillbaka till Spotnana UI.

Ny användare

Diagrammet och stegen nedan visar hur Spotnana UI samarbetar med backend-tjänsterna för att autentisera en ny användare (eller en befintlig användare som vill återställa sitt lösenord).

Figur: Ett sekvensdiagram som visar lösenordsbaserad autentisering för nya användare.

Steg	Flöde
En ny användare anger sin e-postadress på Spotnanas OBT-inloggningssida och klickar på Nästa.
1	Spotnana UI skickar en API-förfrågan till Spotnanas server för att hämta användarens autentiseringsinställningar. Förfrågan innehåller användarens inloggningsuppgifter som parametrar. Svaret innehåller användarens `tmcId`, `orgId`och `authProviderType`.
1 a	Användaren anger ett nytt lösenord och klickar på Nästa.
2	Spotnana UI skickar en API-förfrågan till Spotnana IdP för att registrera användaren tillsammans med `clientId`, e-postadress och nytt lösenord. När uppgifterna har registrerats skickas en engångskod (OTP) till användarens e-postadress.
3	Användaren anger OTP-koden i Spotnana UI och klickar på Verifiera. Spotnana UI skickar en förfrågan till Spotnana IdP för att verifiera OTP och skapa en bearer token för inloggning. Bearertoken genereras och returneras till Spotnana UI. Detta innebär att användaren nu är autentiserad och kan använda Spotnanas plattform med denna bearer token.
4	När användaren har autentiserats i steg 3 måste alla efterföljande API-anrop innehålla bearer token, `orgId`och `tmcId` i anropets header. Bearertoken verifieras i samtliga inkommande API-anrop och svaret skickas tillbaka till Spotnana UI.

IdP-baserad autentisering

Spotnana stödjer autentisering via identitetsleverantörer (IdP) såsom Google, Azure och egna IdP:er med OpenID Connect eller SAML-protokoll. Sekvensdiagrammet och stegen nedan visar hur IdP-baserad autentisering går till.

Figur: Ett sekvensdiagram som visar IdP-baserat autentiseringsflöde.

Steg	Flöde
En användare loggar in via OBT eller Spotnanas mobilapp med sin e-postadress.
1	Spotnana UI skickar en API-förfrågan till Spotnanas server för att hämta användarens autentiseringsinställningar. Förfrågan innehåller användarens inloggningsuppgifter som parametrar. Svaret innehåller användarens `tmcId`, `orgId`och `authProviderType`.
2	Spotnana UI skickar vidare förfrågan till Spotnana IdP.
3	Spotnana IdP skickar vidare förfrågan till partnerns IdP, vilket startar autentiseringen hos IdP:n. Observera: Vid varje omdirigering returneras statuskod 302 för att visa att förfrågan har skickats vidare till en annan URL.
4	En anslutning etableras mellan Spotnana IdP och partnerns IdP för att säkerställa att användaren autentiseras av partnerns IdP. Observera: Under denna anslutning skickar Spotnana IdP `clientId` och `clientSecret` som URL-kodad data via ett API-anrop till partnerns IdP. Om IdP-servern inte kan hantera detta dataformat kan Spotnanas server agera mellanhand och översätta datan till ett format som partnerns IdP accepterar.
5	Partnerns IdP autentiserar användaren. Observera: Efter detta steg måste användarprofilen fortfarande verifieras med bearer token.
5 a	När autentiseringen lyckats skickas svaret från partnerns IdP till Spotnana IdP.
5 b	Spotnana IdP skapar en unik kod för användarprofilen och skickar den till Spotnana UI.
6	Spotnana UI skickar en API-förfrågan till Spotnana IdP med `clientID` och koden från steg 5(b). Spotnana IdP genererar en ny bearer token och skickar den till Spotnana UI. Observera: När en bearer token har skapats innebär det att användaren är autentiserad och har tillgång till Spotnana.
7	När användaren har autentiserats i steg 6 måste alla efterföljande API-anrop innehålla bearer token, `orgId`och `tmcId` i anropets header. Bearertoken verifieras i samtliga inkommande API-anrop och svaret skickas tillbaka till Spotnana UI.

API-baserad autentisering

Partners som ansluter till Spotnanas plattform via våra API:er kan använda vårt autentiserings-endpoint för att generera en bearer token till sina användare. Sekvensdiagrammet nedan visar hur autentiseringsflödet ser ut för partners som använder API-baserad autentisering.

Figur: Ett sekvensdiagram som visar API-baserad autentisering.

Steg Flöde

Steg	Flöde
1	API-användaren gör ett POST anrop till `get-auth-token(clientId,clientSecret)` API-endpoint på Spotnanas server för att skapa och hämta en tillfällig bearer token. Nedan ser du ett exempel på cUrl-anrop för att använda `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>" }' Observera: Ersätt `clientId` och `clientSecret` med de uppgifter du fått från Spotnana.
2	Spotnanas server anropar `getToken(clientId,clientSecret)` metoden i Spotnana IdP, som genererar en tillfällig `bearerToken` och skickar tillbaka den till Spotnanas server. Spotnanas server skickar sedan denna bearer token som ett JSON-svar till API-användaren.

API-användaren gör ett POST anrop till get-auth-token(clientId,clientSecret) API-endpoint på Spotnanas server för att skapa och hämta en tillfällig bearer token.

Nedan ser du ett exempel på cUrl-anrop för att använda 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>"
}'

Observera: Ersätt clientId och clientSecret med de uppgifter du fått från Spotnana.

Spotnanas server anropar getToken(clientId,clientSecret) metoden i Spotnana IdP, som genererar en tillfällig bearerToken och skickar tillbaka den till Spotnanas server.
Spotnanas server skickar sedan denna bearer token som ett JSON-svar till API-användaren.

När API-användaren har fått bearer token måste alla efterföljande anrop till Spotnanas API:er (till exempel Trip APIs) inkludera bearer token i headern för att få åtkomst.

Observera: Endpointen get-auth-token(clientId, clientSecret) har en begränsning på 100 API-anrop per 5 minuter.

iFrame-baserad autentisering

Med iFrame eller inbäddad lösning menas att partnern bäddar in Spotnana UI i sitt eget gränssnitt, så att användarna når Spotnana via partnerns UI. I detta fall sker autentiseringen genom tokenutbyte mellan partnerns och Spotnanas system.

Observera: Vid iFrame-baserad autentisering kallas den användare som loggar in för caller. Detta för att kunna hantera scenarier där en API-/maskinanvändare loggar in och begär en access token för någon annan användare. API-/maskinanvändaren kan till exempel vara en TMC-administratör som kopplar upp sig direkt mot Spotnanas server. Därför används caller som ett samlingsbegrepp, och kan syfta både på en användare som loggar in på sitt eget konto eller en API-/maskinanvändare som begär en access token för någon annan.

Nedan visas ett sekvensdiagram över hur autentiseringsflödet hanteras via tokenutbyte mellan Spotnana och partnerns servrar.

Figur: Ett sekvensdiagram som visar iFrame-baserad autentisering via tokenutbyte.

Steg	Flöde
En caller loggar in via partnerns UI.
1	Partnerns UI visar Spotnana UI via en iFrame.
2	Spotnana UI skickar en förfrågan till partnerns UI via post message för att hämta tokens. Förfrågan skickas med `type=TOKEN_EXCHANGE_REQUEST`.
3	Partnerns UI skickar en API-förfrågan till partnerns server för att hämta OAuth-token och påbörjar nästa steg i autentiseringsflödet.
3 a	Partnerns server anropar Spotnanas server med användaruppgifter och subject token som parametrar. Spotnanas server kontrollerar om förfrågan kommer från en API-/maskinanvändare.
3 b	Spotnanas server anropar partnerns server för att hämta e-postadressen till subject (alltså caller). E-postadressen hämtas och skickas tillbaka till Spotnanas server, som använder den för att identifiera användaren.
3 c	Svaret på API-förfrågan från steg 1 skickas från Spotnanas server till partnerns server och innehåller access token och refresh token. Dessa uppgifter skickas sedan vidare till partnerns UI.
4	Partnerns UI skickar token till Spotnana UI via post message med `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI skickar en API-förfrågan till Spotnanas server för att skapa och hämta en ny bearer token. En bearer token genereras av Spotnanas server och returneras till Spotnana UI. Observera: När en bearer token har skapats innebär det att användaren är autentiserad och har tillgång till Spotnana.
6	När användaren har autentiserats i steg 3 måste alla efterföljande API-anrop innehålla bearer token, `orgId`och `tmcId` i anropets header. Bearertoken verifieras i samtliga inkommande API-anrop och svaret skickas tillbaka till Spotnana UI.

Autentisering med auktoriseringskod

Nedan visas ett sekvensdiagram över hur autentiseringsflödet hanteras med hjälp av en auktoriseringskod.

Figur: Ett sekvensdiagram som visar autentisering med auktoriseringskod.

Steg	Flöde
1	Partnerns UI anropar partnerns server för att hämta auktoriseringskoden för den caller som loggar in. Koden hämtas och skickas tillbaka till partnerns UI.
2	Partnerns UI skickar en förfrågan till Spotnana UI via en anpassad redirect-URL som innehåller `tmcId` och `authCode` som parametrar.
3	Spotnana UI gör ett POST API-anrop till Spotnanas server med `v2/auth/token/companies/<tmcId>(authCode)` API-endpoint.
3 a	Spotnanas server skickar en förfrågan till partnerns server för att hämta användarens `pid` med hjälp av auktoriseringskoden. Användarens `pid` hämtas och skickas till Spotnanas server.
3 b	Access token och refresh token genereras av Spotnanas server och skickas till Spotnana UI.
4	Spotnana UI skickar en förfrågan till Spotnanas server med access token och refresh token för att skapa och hämta en bearer token. En bearer token genereras och skickas till Spotnana UI. Observera: När en bearer token har skapats innebär det att användaren är autentiserad och har tillgång till Spotnana.
5	När användaren har autentiserats i steg 4 måste alla efterföljande API-anrop innehålla bearer token, `orgId`och `tmcId` i anropets header. Bearertoken verifieras i samtliga inkommande API-anrop och svaret skickas tillbaka till Spotnana UI.

Observera: Detta autentiseringsflöde kan inte användas om en TMC-administratör tillåter att flera användare loggar in med samma e-postadress.

Maskin-till-maskin (M2M) autentisering

M2M-autentisering är lämplig när klientapplikationen behöver gå via en extern callback-URL för att skapa en accessToken till användaren. Sekvensdiagrammet nedan visar hur M2M-autentisering går till.

Figur: Ett sekvensdiagram som visar M2M-autentiseringsflöde.

Steg	Flöde
De publika nycklarna för samtliga applikationer som används i autentiseringen synkroniseras mellan Spotnanas server och Spotnana IdP. Dessa används senare för att verifiera access token under autentiseringsflödet.
1	Partnerns server skickar en API-förfrågan till `/oauth2/token(clientId,clientSecret)` i Spotnana IdP för att skapa en bearer token. Den nya bearer token skickas tillbaka till partnerns server.
2	Partnerns server skickar en API-förfrågan till en extern callback-URL för att skapa en access token till användaren. Denna access token skapas och skickas till Spotnanas server.
3	Spotnanas server verifierar signaturen på access token med hjälp av de publika nycklar som synkroniserats tidigare. Den kontrollerar även `claim_id` som bekräftar partnerns identitet. Access token skickas därefter till partnerns server för att autentisera användaren.