Oversikt over autentiseringsmetoder i Spotnana

Opprettet av Ashish Chaudhary, Endret Sun, 5 Okt ved 8:11 PM av Ashish Chaudhary

Spotnana autentiseringsflyter – Oversikt

INNHOLDSFORTEGNELSE

Spotnana autentiseringsflyter – Oversikt
- Nøkkelkomponenter
- Støttede autentiseringsmetoder

Spotnana tilbyr flere ulike autentiseringsmetoder slik at våre partnere kan integrere seg sikkert med plattformen vår. Denne dokumentasjonen gir en oversikt over de ulike autentiseringsmetodene Spotnana støtter, med detaljerte forklaringer på hvordan de fungerer i praksis. De ulike autentiseringsflytene som beskrives her viser hvordan Spotnana autentiserer og gir brukere tilgang til beskyttede ressurser på organisasjonsnivå (det vil si ressurser som tilhører brukerens selskap på Spotnana-plattformen).

Nøkkelkomponenter

Før du setter i gang, anbefaler vi at du ser gjennom denne listen med forklaringer på de viktigste systemkomponentene som omtales i dokumentasjonen.

Spotnana UI(Spotnana brukergrensesnitt) Viser til Spotnanas frontend-nettapplikasjon (altså Online Booking Tool) eller Spotnana sin mobilapp. Her siktes det spesielt til innloggingssiden, som setter i gang autentiseringsflyten når brukeren logger inn eller oppretter ny innlogging.
Spotnana-server Viser til Spotnanas backend-server som brukes til autentiseringsformål (for eksempel for å gi brukere tilgang til ressurser, samt lagre og behandle brukerdata på en trygg måte).
Partner UI (Partnerens brukergrensesnitt) Brukergrensesnittet (altså frontend-applikasjonen) som partnerne benytter for å få tilgang til Spotnana-plattformen. For eksempel, ved iFrame-basert autentisering, er Spotnana-plattformen integrert i partnerens brukergrensesnitt, slik at deres brukere får tilgang til Spotnana via partnerens UI.
Partner-server Viser til én eller flere backend-servere som våre partnere bruker for å integrere seg med Spotnana.
Spotnana IdP (Spotnana Identity Provider) Viser til Spotnanas interne tjeneste for håndtering av brukeridentitet og tilgangsstyring.
Partner IdP Tredjeparts identitetsleverandører (IdP) som partnerne benytter. Vanlige eksempler er Google og Azure.
OBT Spotnanas Online Booking Tool (OBT), som du finner på https://app.spotnana.com/
Subject token I iFrame-basert (eller token-bytte) autentisering representerer et subject token brukerens identitet. Denne tokenen brukes til å hente frem brukerens informasjon og gi tilgang til Spotnana-plattformen.
Access token En tilgangsnøkkel (OAuth) som partnerapplikasjonen bruker for å få tilgang til beskyttede ressurser på vegne av en bruker. Dette er en midlertidig autorisasjonsnøkkel som lar applikasjoner gjøre API-forespørsler uten å eksponere brukerens innloggingsinformasjon.
Refresh token En langtidsnøkkel som brukes for å hente ut nye access tokens uten at brukeren må logge inn på nytt. Denne utstedes vanligvis sammen med access token ved første innlogging.
Klientlegitimasjon Informasjonen som gis til brukere som kobler seg direkte til Spotnana sine API-er (altså en unik clientId og clientSecret).
PID (Personlig identifikator) En personlig identifikator som opprettes for brukeren. PID brukes til å hente ut brukerens informasjon fra Spotnana-serveren.
orgId En unik identifikator som Spotnana tildeler brukerens organisasjon.
tmcId En unik identifikator som Spotnana tildeler et TMC (Travel Management Company).

Støttede autentiseringsmetoder

Spotnana støtter følgende autentiseringsmetoder:

Autentisering med passord
- Eksisterende bruker
- Ny bruker
IdP-basert autentisering
API-basert autentisering
iFrame-basert autentisering
Autentisering med autorisasjonskode
Maskin-til-maskin (M2M) autentisering

Autentisering med passord

Når du bruker autentisering med passord, er det Spotnana sitt brukergrensesnitt (for eksempel innloggings- eller registreringssiden i OBT) som setter i gang og styrer autentiseringen mot Spotnana sine backend-servere. Denne metoden kan ha to ulike flyter, avhengig av om brukeren logger inn med en eksisterende profil eller oppretter en ny. Begge disse flytene forklares i detalj under, med tilhørende sekvensdiagrammer.

Eksisterende bruker

Sekvensdiagrammet og stegene under viser hvordan Spotnana UI samhandler med backend-tjenestene for å autentisere en eksisterende bruker.

Figur: Et sekvensdiagram som forklarer passordbasert autentisering for eksisterende brukere.

Steg	Flyt
En eksisterende bruker logger inn via OBT eller Spotnana sin mobilapp med sin e-postadresse.
1	Spotnana UI sender en API-forespørsel til Spotnana-serveren for å hente autentiseringskonfigurasjon for brukeren. Forespørselen inneholder brukerens innloggingsinformasjon som parametere. Responsen inneholder brukerens `tmcId`, `orgId`, og `authProviderType`.
2	Spotnana UI sender en API-forespørsel til Spotnana IdP med `clientId`, e-post og passord. Spotnana IdP genererer en ny bearer token og returnerer denne til Spotnana UI. Denne handlingen autentiserer brukeren.
3	Når brukeren er autentisert i steg 2, må alle videre API-forespørsler inneholde bearer token, `orgId`, og `tmcId` i forespørselens header. Bearertokenen valideres i alle innkommende API-forespørsler, og svaret sendes tilbake til Spotnana UI.

Ny bruker

Sekvensdiagrammet og stegene under viser hvordan Spotnana UI samhandler med backend-tjenestene for å autentisere en ny bruker (eller en eksisterende bruker som prøver å tilbakestille passordet sitt).

Figur: Et sekvensdiagram som forklarer passordbasert autentisering for nye brukere.

Steg	Flyt
En ny bruker skriver inn e-postadressen sin på innloggingssiden til Spotnana OBT og klikker på Neste.
1	Spotnana UI sender en API-forespørsel til Spotnana-serveren for å hente autentiseringskonfigurasjon for brukeren. Forespørselen inneholder brukerens innloggingsinformasjon som parametere. Responsen inneholder brukerens `tmcId`, `orgId`, og `authProviderType`.
1 a	Brukeren skriver inn et nytt passord og klikker på Neste.
2	Spotnana UI sender en API-forespørsel til Spotnana IdP for å registrere brukeren sammen med `clientId`, e-post og nytt passord. Når opplysningene er registrert, sendes en engangskode (OTP) til brukerens e-postadresse.
3	Brukeren skriver inn OTP-koden i Spotnana UI og klikker på Verifiser. Spotnana UI sender en forespørsel til Spotnana IdP for å verifisere OTP og generere en bearer token for innlogging. Bearertokenen genereres og returneres til Spotnana UI. Dette betyr at brukeren nå er autentisert og kan bruke Spotnana-plattformen med denne tokenen.
4	Når brukeren er autentisert i steg 3, må alle videre API-forespørsler inneholde bearer token, `orgId`, og `tmcId` i forespørselens header. Bearertokenen valideres i alle innkommende API-forespørsler, og svaret sendes tilbake til Spotnana UI.

IdP-basert autentisering

Spotnana støtter autentisering via IdP-er som Google, Azure og egne IdP-er ved bruk av OpenID Connect, samt SAML-protokoller. Sekvensdiagrammet og stegene under viser hvordan IdP-basert autentisering foregår.

Figur: Et sekvensdiagram som forklarer IdP-basert autentiseringsflyt.

Steg	Flyt
En bruker logger inn via OBT eller Spotnana sin mobilapp med sin e-postadresse.
1	Spotnana UI sender en API-forespørsel til Spotnana-serveren for å hente autentiseringskonfigurasjon for brukeren. Forespørselen inneholder brukerens innloggingsinformasjon som parametere. Responsen inneholder brukerens `tmcId`, `orgId`, og `authProviderType`.
2	Spotnana UI videresender forespørselen til Spotnana IdP.
3	Spotnana IdP videresender forespørselen til partnerens IdP. Dette starter autentiseringen mot IdP for brukeren. Merk: For hver videresending returneres statuskode 302 for å indikere at forespørselen er sendt til en annen adresse.
4	Det opprettes en forbindelse mellom Spotnana IdP og partnerens IdP. Denne forbindelsen sikrer at brukeren autentiseres av partnerens IdP. Merk: I denne forbindelsen sender Spotnana IdP `clientId` og `clientSecret` som URL-kodede data via en API-kall til Partner IdP. Hvis IdP-serverne ikke kan behandle dette dataformatet, kan Spotnana-serveren fungere som mellomledd og oversette dataene til et format partnerens IdP støtter.
5	Partnerens IdP autentiserer brukeren. Merk: Etter dette steget må brukerprofilen fortsatt gjennomgå verifisering av bearer token.
5 a	Når autentiseringen er vellykket, sendes svaret fra partnerens IdP til Spotnana IdP.
5 b	Spotnana IdP genererer en unik kode for brukerprofilen og sender den til Spotnana UI.
6	Spotnana UI sender en API-forespørsel til Spotnana IdP med `clientID` og koden mottatt i steg 5(b). Spotnana IdP genererer en ny bearer token og sender denne til Spotnana UI. Merk: Når bearer token er opprettet, betyr det at brukeren er autentisert og får tilgang til Spotnana.
7	Når brukeren er autentisert i steg 6, må alle videre API-forespørsler inneholde bearer token, `orgId`, og `tmcId` i forespørselens header. Bearertokenen valideres i alle innkommende API-forespørsler, og svaret sendes tilbake til Spotnana UI.

API-basert autentisering

Partnere som bruker Spotnana sine API-er for å koble seg til plattformen, kan benytte vårt autentiserings-endepunkt for å generere en bearer token til sine brukere. Sekvensdiagrammet under viser hvordan autentiseringsflyten fungerer for partnere som bruker API-basert autentisering.

Figur: Et sekvensdiagram som forklarer API-basert autentisering.

Steg Flyt

Steg	Flyt
1	API-brukeren gjør et POST kall til `get-auth-token(clientId,clientSecret)` API-endepunktet på Spotnana-serveren for å generere og hente ut en midlertidig bearer token. Her er et eksempel på cUrl-forespørsel du kan bruke mot `get-auth-token` endepunktet: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Merk: Bytt ut verdiene for `clientId` og `clientSecret` med legitimasjonen du har mottatt fra Spotnana.
2	Spotnana-serveren kaller `getToken(clientId,clientSecret)` metoden i Spotnana IdP, som genererer en midlertidig `bearerToken` og sender den tilbake til Spotnana-serveren. Spotnana-serveren sender denne bearer tokenen som et JSON-svar til API-brukeren.

API-brukeren gjør et POST kall til get-auth-token(clientId,clientSecret) API-endepunktet på Spotnana-serveren for å generere og hente ut en midlertidig bearer token.

Her er et eksempel på cUrl-forespørsel du kan bruke mot get-auth-token endepunktet:

curl -i -X POST \
https://api.spotnana.com/get-auth-token \
-H 'Content-Type: application/json' \
-d '{
  "clientId": "sample-apiuser@tmcorg.com",
  "clientSecret": "<password>"
}'

Merk: Bytt ut verdiene for clientId og clientSecret med legitimasjonen du har mottatt fra Spotnana.

Spotnana-serveren kaller getToken(clientId,clientSecret) metoden i Spotnana IdP, som genererer en midlertidig bearerToken og sender den tilbake til Spotnana-serveren.
Spotnana-serveren sender denne bearer tokenen som et JSON-svar til API-brukeren.

Når API-brukeren har mottatt bearer tokenen, må alle videre forespørsler til Spotnana sine API-er (for eksempel Trip APIs) inkludere bearer token i headeren for å få tilgang.

Merk: Endepunktet get-auth-token(clientId, clientSecret) har en grense på 100 API-kall per 5 minutter.

iFrame-basert autentisering

En iFrame eller innebygd løsning betyr at partnerne legger Spotnana UI inn i sitt eget brukergrensesnitt, slik at brukerne får tilgang til Spotnana via partnerens UI. I dette tilfellet håndteres autentiseringen gjennom token-bytte mellom partnerens og Spotnana sine systemer.

Merk: Ved iFrame-basert autentisering omtales brukeren som logger inn som en caller. Dette gjør det mulig å dekke scenarier der en API- eller maskinbruker logger inn og ber om tilgangstoken på vegne av en annen bruker. En slik API- eller maskinbruker kan for eksempel bruke TMC-administratorrettigheter for å koble seg direkte til Spotnana-serveren. Derfor bruker vi caller som en generell betegnelse, enten det gjelder en bruker som logger inn på egen profil eller en API-/maskinbruker som ber om tilgangstoken for en annen.

Sekvensdiagrammet under viser hvordan autentiseringsflyten håndteres med token-bytte mellom Spotnana og partnerens servere.

Figur: Et sekvensdiagram som forklarer iFrame-basert autentisering med token-bytte.

Steg	Flyt
En caller logger inn via partnerens brukergrensesnitt.
1	Partnerens UI viser Spotnana UI via iFrame.
2	Spotnana UI sender en forespørsel til partnerens UI via post message for å hente tokens. Forespørselen sendes med `type=TOKEN_EXCHANGE_REQUEST`.
3	Partnerens UI sender en API-forespørsel til partnerens server for å hente ut OAuth-token, og starter de neste stegene i autentiseringsflyten.
3 a	Partnerens server kaller Spotnana-serveren med brukerinformasjon og subject token som parametere. Spotnana-serveren sjekker om forespørselen kommer fra en API-/maskinbruker.
3 b	Spotnana-serveren kaller partnerens server for å hente ut e-postadressen til subject (altså calleren). E-posten hentes og returneres til Spotnana-serveren, som bruker den for å identifisere brukeren.
3 c	Responsen på API-forespørselen fra steg 1 sendes fra Spotnana-serveren til partnerens server og inneholder access token og refresh token. Disse detaljene sendes så videre til partnerens UI.
4	Partnerens UI sender tokenen til Spotnana UI via post message med `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI sender en API-forespørsel til Spotnana-serveren for å generere og hente ut en ny bearer token. En bearer token genereres av Spotnana-serveren og returneres til Spotnana UI. Merk: Når bearer token er opprettet, betyr det at brukeren er autentisert og får tilgang til Spotnana.
6	Når brukeren er autentisert i steg 3, må alle videre API-forespørsler inneholde bearer token, `orgId`, og `tmcId` i forespørselens header. Bearertokenen valideres i alle innkommende API-forespørsler, og svaret sendes tilbake til Spotnana UI.

Autentisering med autorisasjonskode

Sekvensdiagrammet under viser hvordan autentiseringsflyten fungerer ved bruk av autorisasjonskode.

Figur: Et sekvensdiagram som forklarer autentisering med autorisasjonskode.

Steg	Flyt
1	Partnerens UI kaller partnerens server for å hente autorisasjonskoden for calleren som logger inn. Koden hentes og sendes tilbake til partnerens UI.
2	Partnerens UI sender en forespørsel til Spotnana UI via en tilpasset redirect-URL som inneholder `tmcId` og `authCode` som parametere.
3	Spotnana UI gjør et POST API-kall til Spotnana-serveren med `v2/auth/token/companies/<tmcId>(authCode)` API-endepunktet.
3 a	Spotnana-serveren sender en forespørsel til partnerens server for å hente brukerens `pid` ved hjelp av autorisasjonskoden. Brukerens `pid` hentes og sendes til Spotnana-serveren.
3 b	Access token og refresh token genereres av Spotnana-serveren og sendes til Spotnana UI.
4	Spotnana UI sender en forespørsel til Spotnana-serveren med access token og refresh token for å generere og hente ut en bearer token for tilgang. En bearer token genereres og sendes til Spotnana UI. Merk: Når bearer token er opprettet, betyr det at brukeren er autentisert og får tilgang til Spotnana.
5	Når brukeren er autentisert i steg 4, må alle videre API-forespørsler inneholde bearer token, `orgId`, og `tmcId` i forespørselens header. Bearertokenen valideres i alle innkommende API-forespørsler, og svaret sendes tilbake til Spotnana UI.

Merk: Denne autentiseringsflyten kan ikke brukes der en TMC-administrator tillater at flere brukere logger inn med samme e-postadresse.

Maskin-til-maskin (M2M) autentisering

M2M-autentisering egner seg når klientapplikasjonen må kontakte en tredjeparts callback-URL for å generere accessToken for brukeren. Sekvensdiagrammet under viser hvordan M2M-autentiseringsflyten fungerer.

Figur: Et sekvensdiagram som forklarer M2M-autentiseringsflyten.

Steg	Flyt
De offentlige nøklene for alle applikasjoner som brukes i autentiseringen, synkroniseres mellom Spotnana-serveren og Spotnana IdP. Disse brukes senere for å verifisere access token i autentiseringsflyten.
1	Partnerens server sender en API-forespørsel til `/oauth2/token(clientId,clientSecret)` i Spotnana IdP for å generere en bearer token. Den nye bearer tokenen sendes tilbake til partnerens server.
2	Partnerens server sender en API-forespørsel til en tredjeparts callback-URL for å generere en access token for brukeren. Access tokenen opprettes og sendes til Spotnana-serveren.
3	Spotnana-serveren validerer signaturen på access token ved hjelp av de synkroniserte offentlige nøklene. Den sjekker også `claim_id` som bekrefter partnerens identitet. Access tokenen sendes deretter til partnerens server for å autentisere brukeren.