Overzicht van Spotnana-authenticatieprocessen

Gemaakt door Ashish Chaudhary, Gewijzigd op Za, 4 Okt om 9:50 PM op Ashish Chaudhary

Spotnana-authenticatiestromen – Overzicht

INHOUDSOPGAVE

Spotnana-authenticatiestromen – Overzicht
- Belangrijke onderdelen
- Ondersteunde authenticatiemethoden

Spotnana biedt verschillende manieren van authenticatie waarmee partners veilig kunnen koppelen met ons platform. In deze documentatie vindt u een overzicht van de verschillende authenticatiemethoden die Spotnana momenteel ondersteunt, inclusief een uitleg van het verloop van elk proces. De beschreven authenticatiestromen laten zien hoe Spotnana gebruikers verifieert en autoriseert voor toegang tot beveiligde bedrijfsgegevens (oftewel de gegevens van het bedrijf van de gebruiker binnen het Spotnana-platform).

Belangrijke onderdelen

Voordat u aan de slag gaat, raden we aan om deze lijst met definities van de belangrijkste systeemonderdelen door te nemen. Deze termen worden in deze documentatie regelmatig gebruikt.

Spotnana UI(Spotnana Gebruikersinterface) Dit verwijst naar de webapplicatie van Spotnana (ook wel de Online Booking Tool genoemd) of de mobiele applicatie van Spotnana. In het bijzonder gaat het om de inlogpagina, waar het authenticatieproces aan de voorkant start zodra een gebruiker inlogt of een nieuw account aanmaakt.
Spotnana-server Dit is de backendserver van Spotnana die wordt gebruikt voor authenticatie, zoals het autoriseren van gebruikers voor toegang tot gegevens en het veilig opslaan en verwerken van gebruikersinformatie.
Partner UI (Gebruikersinterface van de partner) De gebruikersinterface (dus de frontend-applicatie) die partners gebruiken om toegang te krijgen tot het Spotnana-platform. Bij authenticatie via iFrame wordt het Spotnana-platform bijvoorbeeld geïntegreerd in de gebruikersinterface van de partner, zodat hun gebruikers via deze omgeving bij Spotnana kunnen inloggen.
Partner-server Dit zijn een of meerdere backendservers die onze partners gebruiken om te koppelen met Spotnana.
Spotnana IdP (Spotnana Identity Provider) Dit is de interne dienst van Spotnana voor het beheren van gebruikersidentiteiten en autorisaties.
Partner IdP Externe Identity Providers (IdP) die door partners worden gebruikt. Veelvoorkomende voorbeelden zijn Google en Azure.
OBT De Online Booking Tool (OBT) van Spotnana, te bereiken via https://app.spotnana.com/
Subject token Bij authenticatie via iFrame (of tokenuitwisseling) staat het subject token voor de identiteit van de gebruiker. Met deze token kan Spotnana de gebruiker herkennen en autoriseren voor toegang tot het platform.
Access token Een toegangsbewijs (OAuth) waarmee een partnerapplicatie namens een gebruiker beveiligde gegevens kan opvragen. Dit is een tijdelijke sleutel waarmee applicaties API-verzoeken kunnen doen zonder de inloggegevens van de gebruiker prijs te geven.
Refresh token Een lang geldig toegangsbewijs waarmee nieuwe access tokens kunnen worden aangevraagd zonder dat de gebruiker opnieuw hoeft in te loggen. Meestal ontvangt de gebruiker deze samen met het access token bij de eerste inlogsessie.
Client credentials De gegevens die gebruikers ontvangen wanneer zij direct verbinding maken met de Spotnana API’s (dit betreft een unieke clientId en clientSecret).
PID (Persoonlijke identificatie) Een persoonlijke identificatiecode die voor de gebruiker wordt aangemaakt. Met deze PID kan de gebruikersinformatie bij de Spotnana-server worden opgehaald.
orgId Een unieke code die Spotnana toekent aan de organisatie van de gebruiker.
tmcId Een unieke code die Spotnana toekent aan een TMC (Travel Management Company).

Ondersteunde authenticatiemethoden

Spotnana ondersteunt de volgende authenticatiemethoden:

Authenticatie op basis van wachtwoord
- Bestaande gebruiker
- Nieuwe gebruiker
Authenticatie via IdP
Authenticatie via API
Authenticatie via iFrame
Authenticatie op basis van autorisatiecode
Machine-to-machine (M2M) authenticatie

Authenticatie op basis van wachtwoord

Bij authenticatie op basis van wachtwoord start en beheert de Spotnana UI (de inlog- of registratiepagina in de OBT) het proces samen met de backendservers van Spotnana. Afhankelijk van of een gebruiker al een profiel heeft of een nieuw profiel aanmaakt, zijn er twee verschillende stromen. Beide worden hieronder uitgelegd aan de hand van sequentiediagrammen.

Bestaande gebruiker

Het onderstaande sequentiediagram en de stappen leggen uit hoe de Spotnana UI samenwerkt met de backend om een bestaande gebruiker te authenticeren.

Afbeelding: Sequentiediagram van authenticatie op basis van wachtwoord voor bestaande gebruikers.

Stap	Verloop
Een bestaande gebruiker logt in via de OBT of de Spotnana-app met zijn of haar e-mailadres.
1	De Spotnana UI stuurt een API-verzoek naar de Spotnana-server om de authenticatie-instellingen voor de gebruiker op te halen. De inloggegevens van de gebruiker worden als parameters meegestuurd. Het antwoord bevat de `tmcId`, `orgId`en `authProviderType`van de gebruiker.
2	De Spotnana UI stuurt een API-verzoek naar de Spotnana IdP met de `clientId`, het e-mailadres en het wachtwoord. De Spotnana IdP genereert een nieuwe bearer token en stuurt deze terug naar de Spotnana UI. Hiermee is de gebruiker geverifieerd.
3	Nadat de gebruiker in stap 2 is geverifieerd, moeten alle volgende API-verzoeken de bearer token, de `orgId`en de `tmcId` bevatten in de request header. Bij elk inkomend API-verzoek wordt de bearer token gecontroleerd en de reactie teruggestuurd naar de Spotnana UI.

Nieuwe gebruiker

Het onderstaande sequentiediagram en de stappen beschrijven hoe de Spotnana UI samenwerkt met de backend om een nieuwe gebruiker (of een bestaande gebruiker die het wachtwoord wil herstellen) te authenticeren.

Afbeelding: Sequentiediagram van authenticatie op basis van wachtwoord voor nieuwe gebruikers.

Stap	Verloop
Een nieuwe gebruiker vult zijn of haar e-mailadres in op de Spotnana OBT-inlogpagina en klikt op Volgende.
1	De Spotnana UI stuurt een API-verzoek naar de Spotnana-server om de authenticatie-instellingen voor de gebruiker op te halen. De inloggegevens van de gebruiker worden als parameters meegestuurd. Het antwoord bevat de `tmcId`, `orgId`en `authProviderType`van de gebruiker.
1 a	De gebruiker voert een nieuw wachtwoord in en klikt op Volgende.
2	De Spotnana UI stuurt een API-verzoek naar de Spotnana IdP om de gebruiker te registreren, samen met de `clientId`, het e-mailadres en het nieuwe wachtwoord. Nadat deze gegevens zijn geregistreerd, ontvangt de gebruiker een eenmalige code (OTP) per e-mail.
3	De gebruiker voert de OTP in de Spotnana UI in en klikt op Verifiëren. De Spotnana UI stuurt een verzoek naar de Spotnana IdP om de OTP te controleren en een bearer token voor inloggen te genereren. De bearer token wordt gegenereerd en teruggestuurd naar de Spotnana UI. Hiermee is de gebruiker succesvol geverifieerd en kan deze het Spotnana-platform benaderen met de bearer token.
4	Nadat de gebruiker in stap 3 is geverifieerd, moeten alle volgende API-verzoeken de bearer token, de `orgId`en de `tmcId` bevatten in de request header. Bij elk inkomend API-verzoek wordt de bearer token gecontroleerd en de reactie teruggestuurd naar de Spotnana UI.

Authenticatie via IdP

Spotnana ondersteunt authenticatie via IdP’s zoals Google, Azure en eigen IdP’s via OpenID Connect of SAML-protocollen. Het onderstaande sequentiediagram en de stappen leggen de authenticatiestroom via IdP uit.

Afbeelding: Sequentiediagram van authenticatie via IdP.

Stap	Verloop
Een gebruiker logt in via de OBT of de Spotnana-app met zijn of haar e-mailadres.
1	De Spotnana UI stuurt een API-verzoek naar de Spotnana-server om de authenticatie-instellingen voor de gebruiker op te halen. De inloggegevens van de gebruiker worden als parameters meegestuurd. Het antwoord bevat de `tmcId`, `orgId`en `authProviderType`van de gebruiker.
2	De Spotnana UI leidt het verzoek door naar de Spotnana IdP.
3	De Spotnana IdP stuurt het verzoek door naar de IdP van de partner. Hiermee wordt de authenticatie bij de IdP gestart. Noot: Bij elke doorverwijzing wordt een 302-statuscode teruggegeven om aan te geven dat het verzoek naar een andere URL is doorgestuurd.
4	Er wordt een verbinding gelegd tussen de Spotnana IdP en de partner IdP om te controleren of de gebruiker daar succesvol is geverifieerd. Noot: Tijdens deze verbinding stuurt de Spotnana IdP de `clientId` en `clientSecret` als URL-gecodeerde gegevens via een API-verzoek naar de partner IdP. Als de IdP-servers dit formaat niet kunnen verwerken, kan de Spotnana-server als tussenstation optreden en de gegevens omzetten naar een formaat dat de partner IdP wel accepteert.
5	De partner IdP verifieert de gebruiker succesvol. Noot: Na deze stap moet het gebruikersprofiel nog gecontroleerd worden via de bearer token.
5 a	Na succesvolle verificatie stuurt de partner IdP het antwoord naar de Spotnana IdP.
5 b	De Spotnana IdP maakt een unieke code aan voor het gebruikersprofiel en stuurt deze naar de Spotnana UI.
6	De Spotnana UI stuurt een API-verzoek naar de Spotnana IdP met de `clientID` en de code uit stap 5(b). De Spotnana IdP genereert een nieuwe bearer token en stuurt deze naar de Spotnana UI. Noot: Als de bearer token succesvol is aangemaakt, is de gebruiker geverifieerd en heeft deze toegang tot Spotnana.
7	Nadat de gebruiker in stap 6 is geverifieerd, moeten alle volgende API-verzoeken de bearer token, de `orgId`en de `tmcId` bevatten in de request header. Bij elk inkomend API-verzoek wordt de bearer token gecontroleerd en de reactie teruggestuurd naar de Spotnana UI.

Authenticatie via API

Partners die Spotnana-API’s gebruiken om verbinding te maken met het platform, kunnen via onze authenticatie-endpoint een bearer token genereren voor hun gebruikers. Het onderstaande sequentiediagram laat zien hoe deze authenticatiestroom verloopt.

Afbeelding: Sequentiediagram van authenticatie via API.

Stap Verloop

Stap	Verloop
1	De API-gebruiker doet een POST verzoek naar de `get-auth-token(clientId,clientSecret)` API-endpoint op de Spotnana-server om een tijdelijke bearer token aan te maken en op te halen. Hieronder vindt u een voorbeeld van een cURL-verzoek voor het aanroepen van de `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>" }' Noot: Vervang de waarden voor `clientId` en `clientSecret` door de inloggegevens die u van Spotnana heeft ontvangen.
2	De Spotnana-server roept de `getToken(clientId,clientSecret)` methode aan in de Spotnana IdP, die een tijdelijke `bearerToken` genereert en terugstuurt naar de Spotnana-server. De Spotnana-server stuurt deze bearer token als JSON-antwoord naar de API-gebruiker.

De API-gebruiker doet een POST verzoek naar de get-auth-token(clientId,clientSecret) API-endpoint op de Spotnana-server om een tijdelijke bearer token aan te maken en op te halen.

Hieronder vindt u een voorbeeld van een cURL-verzoek voor het aanroepen van de 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>"
}'

Noot: Vervang de waarden voor clientId en clientSecret door de inloggegevens die u van Spotnana heeft ontvangen.

De Spotnana-server roept de getToken(clientId,clientSecret) methode aan in de Spotnana IdP, die een tijdelijke bearerToken genereert en terugstuurt naar de Spotnana-server.
De Spotnana-server stuurt deze bearer token als JSON-antwoord naar de API-gebruiker.

Nadat de API-gebruiker de bearer token heeft ontvangen, moeten alle volgende verzoeken aan Spotnana API’s (zoals Trip API’s) de bearer token in de header bevatten voor autorisatie.

Noot: De get-auth-token(clientId, clientSecret) endpoint heeft een limiet van 100 API-aanroepen per 5 minuten.

Authenticatie via iFrame

Bij een iFrame- of embedded-oplossing wordt de Spotnana UI geïntegreerd in de partner UI, waardoor gebruikers via de omgeving van de partner toegang krijgen tot Spotnana. In dit geval verloopt de authenticatie op basis van een tokenuitwisseling tussen de systemen van de partner en Spotnana.

Noot: Bij authenticatie via iFrame wordt de gebruiker die inlogt aangeduid als caller. Dit is om situaties te dekken waarbij een API- of machinegebruiker inlogt en een toegangstoken aanvraagt voor een andere gebruiker. Deze API- of machinegebruiker kan bijvoorbeeld TMC-beheerdersgegevens gebruiken om direct met de Spotnana-server te verbinden. Daarom gebruiken we caller als algemene term, die zowel een gebruiker die inlogt op zijn eigen profiel als een API- of machinegebruiker die een token aanvraagt voor een ander kan aanduiden.

Het onderstaande sequentiediagram laat zien hoe de authenticatiestroom verloopt via tokenuitwisseling tussen Spotnana en de partnerservers.

Afbeelding: Sequentiediagram van authenticatie via iFrame met tokenuitwisseling.

Stap	Verloop
Een caller logt in via de Partner UI.
1	De partner UI laadt de Spotnana UI in een iFrame.
2	De Spotnana UI stuurt een verzoek naar de partner UI via een post message om tokens op te halen. Dit verzoek wordt verstuurd met `type=TOKEN_EXCHANGE_REQUEST`.
3	De Partner UI stuurt een API-verzoek naar de partner-server om het OAuth-token op te halen en start zo de volgende stappen in het authenticatieproces.
3 a	De partner-server roept de Spotnana-server aan met de gebruikersgegevens en het subject token als parameters. De Spotnana-server controleert of het verzoek afkomstig is van een API- of machinegebruiker.
3 b	De Spotnana-server vraagt bij de partner-server het e-mailadres van het subject (de caller) op. Het e-mailadres wordt opgehaald en teruggestuurd naar de Spotnana-server, die hiermee de gebruiker identificeert.
3 c	Het antwoord op het API-verzoek uit stap 1 wordt door de Spotnana-server naar de partner-server gestuurd en bevat het access token en het refresh token. Deze gegevens worden vervolgens doorgestuurd naar de Partner UI.
4	De partner UI stuurt het token naar de Spotnana UI via een post message met `type=TOKEN_EXCHANGE_RESPONSE.`
5	De Spotnana UI stuurt een API-verzoek naar de Spotnana-server om een nieuwe bearer token aan te maken en op te halen. De Spotnana-server genereert een bearer token en stuurt deze terug naar de Spotnana UI. Noot: Als de bearer token succesvol is aangemaakt, is de gebruiker geverifieerd en heeft deze toegang tot Spotnana.
6	Nadat de gebruiker in stap 3 is geverifieerd, moeten alle volgende API-verzoeken de bearer token, de `orgId`en de `tmcId` bevatten in de request header. Bij elk inkomend API-verzoek wordt de bearer token gecontroleerd en de reactie teruggestuurd naar de Spotnana UI.

Authenticatie op basis van autorisatiecode

Het onderstaande sequentiediagram laat zien hoe de authenticatiestroom verloopt met een autorisatiecode.

Afbeelding: Sequentiediagram van authenticatie op basis van autorisatiecode.

Stap	Verloop
1	De partner UI vraagt bij de partner-server de autorisatiecode op voor de caller die inlogt. De code wordt opgehaald en teruggestuurd naar de partner UI.
2	De Partner UI stuurt een verzoek naar de Spotnana UI via een aangepaste redirect-URL met daarin de `tmcId` en `authCode` als parameters.
3	De Spotnana UI doet een POST API-verzoek naar de Spotnana-server via de `v2/auth/token/companies/<tmcId>(authCode)` API-endpoint.
3 a	De Spotnana-server vraagt bij de partner-server de `pid` van de gebruiker op met behulp van de autorisatiecode. De `pid` van de gebruiker wordt opgehaald en naar de Spotnana-server gestuurd.
3 b	Het access token en refresh token worden door de Spotnana-server gegenereerd en naar de Spotnana UI gestuurd.
4	De Spotnana UI stuurt een verzoek naar de Spotnana-server met het access token en refresh token om een bearer token aan te maken en op te halen. De bearer token wordt aangemaakt en naar de Spotnana UI gestuurd. Noot: Als de bearer token succesvol is aangemaakt, is de gebruiker geverifieerd en heeft deze toegang tot Spotnana.
5	Nadat de gebruiker in stap 4 is geverifieerd, moeten alle volgende API-verzoeken de bearer token, de `orgId`en de `tmcId` bevatten in de request header. Bij elk inkomend API-verzoek wordt de bearer token gecontroleerd en de reactie teruggestuurd naar de Spotnana UI.

Noot: Deze authenticatiestroom is niet geschikt als een TMC-beheerder toestaat dat meerdere gebruikers met hetzelfde e-mailadres inloggen.

Machine-to-machine (M2M) authenticatie

De M2M-authenticatiemethode is bedoeld voor situaties waarin een clientapplicatie een derde partij aanroept om een accessToken voor de gebruiker aan te maken. Het onderstaande sequentiediagram laat zien hoe deze authenticatiestroom verloopt.

Afbeelding: Sequentiediagram van de M2M-authenticatiestroom.

Stap	Verloop
De publieke sleutels van alle applicaties die bij de authenticatie betrokken zijn, worden gesynchroniseerd tussen de Spotnana-server en de Spotnana IdP. Deze worden later gebruikt om het access token te controleren tijdens het authenticatieproces.
1	De partner-server stuurt een API-verzoek naar `/oauth2/token(clientId,clientSecret)` in de Spotnana IdP om een bearer token aan te maken. De nieuwe bearer token wordt teruggestuurd naar de partner-server.
2	De partner-server stuurt een API-verzoek naar een externe callback-URL om een access token voor de gebruiker aan te maken. Dit access token wordt aangemaakt en naar de Spotnana-server gestuurd.
3	De Spotnana-server controleert de handtekening van het access token met de eerder gesynchroniseerde publieke sleutels. Ook wordt de `claim_id` gecontroleerd om de identiteit van de partner te verifiëren. Het access token wordt vervolgens naar de partner-server gestuurd om de gebruiker te authenticeren.