Overblik over Spotnanas godkendelsesprocesser

Oprettet af Ashish Chaudhary, Ændret den Sun, 5 Okt kl. 5:36 AM af Ashish Chaudhary

Spotnana-godkendelsesforløb – Overblik

INDHOLDSFORTEGNELSE

Spotnana-godkendelsesforløb – Overblik
- Nøglekomponenter
- Understøttede godkendelsesmetoder

Spotnana tilbyder flere forskellige godkendelsesmetoder, så vores partnere kan integrere sikkert med vores platform. Denne vejledning giver et overblik over de godkendelsesmetoder, Spotnana understøtter i dag, og forklarer trin for trin, hvordan de enkelte forløb fungerer. De forskellige godkendelsesforløb her viser, hvordan Spotnana håndterer godkendelse og adgang for brugere, der skal tilgå beskyttede ressourcer på organisationsniveau (altså de ressourcer, som tilhører brugerens virksomhed på Spotnana-platformen).

Nøglekomponenter

Før du går i gang, kan du med fordel læse denne liste igennem for at få styr på de vigtigste systemkomponenter, som omtales i vejledningen.

Spotnana UI(Spotnana brugergrænseflade) Henviser til Spotnanas webapplikation (Online Booking Tool) eller Spotnanas mobilapp. Mere konkret handler det om loginsiden, hvor brugeren starter godkendelsesforløbet, når vedkommende logger ind eller opretter en ny bruger.
Spotnana-server Henviser til Spotnanas backend-server, som bruges til at håndtere godkendelse (f.eks. give adgang til ressourcer og opbevare samt behandle brugeroplysninger sikkert).
Partner UI (Partnerens brugergrænseflade) Den brugergrænseflade (altså frontend-applikation), som partnere benytter for at få adgang til Spotnana-platformen. For eksempel, ved iFrame-baseret godkendelse, bliver Spotnana-platformen integreret i partnerens brugergrænseflade, og deres brugere får adgang til Spotnana via partnerens UI.
Partner-server Henviser til en eller flere backend-servere, som vores partnere bruger til at integrere med Spotnana.
Spotnana IdP (Spotnana Identity Provider) Henviser til Spotnanas interne tjeneste til håndtering af brugeridentitet og adgangsstyring.
Partner IdP Tredjeparts Identity Providers (IdP), som partnerne anvender. Eksempler på almindelige IdP’er er Google og Azure.
OBT Spotnanas Online Booking Tool (OBT), som kan tilgås på https://app.spotnana.com/
Subject token I iFrame-baseret (eller token-udvekslings-) godkendelse repræsenterer et subject token brugerens identitet. Dette token bruges til at hente brugerens oplysninger og give adgang til Spotnana-platformen.
Access token Et adgangsbevis (OAuth), som partnerapplikationer bruger til at tilgå beskyttede ressourcer på vegne af en bruger. Det fungerer som en midlertidig nøgle, så applikationer kan lave API-kald uden at skulle dele brugerens loginoplysninger.
Refresh token Et langtidsholdbart adgangsbevis, der bruges til at hente nye access tokens, uden at brugeren skal logge ind igen. Dette udstedes typisk sammen med access token ved første login.
Klientoplysninger De informationer, som gives til brugere, der forbinder sig direkte til Spotnanas API’er (altså en unik clientId og clientSecret).
PID (Personligt ID) Et personligt ID, der bliver oprettet til brugeren. PID bruges til at hente brugerens oplysninger fra Spotnana-serveren.
orgId Et unikt ID, som Spotnana tildeler brugerens organisation.
tmcId Et unikt ID, som Spotnana tildeler et TMC (Travel Management Company).

Understøttede godkendelsesmetoder

Nedenfor kan du se de forskellige godkendelsesmetoder, som Spotnana understøtter:

Godkendelse med adgangskode
- Eksisterende bruger
- Ny bruger
IdP-baseret godkendelse
API-baseret godkendelse
iFrame-baseret godkendelse
Godkendelse med autorisationskode
Maskine-til-maskine (M2M) godkendelse

Godkendelse med adgangskode

Når du bruger adgangskodebaseret godkendelse, starter Spotnana UI (altså login- eller oprettelsessiden i OBT) og styrer hele godkendelsesforløbet sammen med Spotnanas backend-servere. Forløbet kan variere, alt efter om brugeren logger ind med en eksisterende profil eller opretter en ny. Begge forløb er beskrevet nedenfor med tilhørende sekvensdiagrammer.

Eksisterende bruger

Diagrammet og trinnene herunder viser, hvordan Spotnana UI arbejder sammen med backend-tjenesterne for at godkende en eksisterende bruger.

Fig: Et sekvensdiagram, der forklarer adgangskodebaseret godkendelse for eksisterende brugere.

Trin	Forløb
En eksisterende bruger logger ind via OBT eller Spotnana-mobilappen med sin e-mailadresse.
1	Spotnana UI sender en API-forespørgsel til Spotnana-serveren for at hente godkendelsesoplysninger for brugeren. Forespørgslen indeholder brugerens loginoplysninger som parametre. Svaret indeholder brugerens `tmcId`, `orgId`, og `authProviderType`.
2	Spotnana UI sender en API-forespørgsel til Spotnana IdP med `clientId`, e-mail og adgangskode. Spotnana IdP opretter et nyt bearer token og sender det retur til Spotnana UI. Dette trin godkender brugeren.
3	Når brugeren er godkendt i trin 2, skal alle efterfølgende API-kald indeholde bearer token, `orgId`og `tmcId` i anmodningshovedet. Bearer token bliver valideret ved alle indgående API-forespørgsler, og svaret sendes tilbage til Spotnana UI.

Ny bruger

Diagrammet og trinnene herunder viser, hvordan Spotnana UI arbejder sammen med backend-tjenesterne for at godkende en ny bruger (eller en eksisterende bruger, der forsøger at nulstille sin adgangskode).

Fig: Et sekvensdiagram, der forklarer adgangskodebaseret godkendelse for nye brugere.

Trin	Forløb
En ny bruger indtaster sin e-mail på Spotnanas OBT-loginside og klikker på Næste.
1	Spotnana UI sender en API-forespørgsel til Spotnana-serveren for at hente godkendelsesoplysninger for brugeren. Forespørgslen indeholder brugerens loginoplysninger som parametre. Svaret indeholder brugerens `tmcId`, `orgId`, og `authProviderType`.
1 a	Brugeren indtaster en ny adgangskode og klikker på Næste.
2	Spotnana UI sender en API-forespørgsel til Spotnana IdP for at registrere brugeren sammen med `clientId`, e-mail og ny adgangskode. Når oplysningerne er registreret, sendes en engangskode (OTP) til brugerens e-mail.
3	Brugeren indtaster OTP i Spotnana UI og klikker på Verificér. Spotnana UI sender en anmodning til Spotnana IdP om at verificere OTP og oprette et bearer token til login. Bearer token oprettes og sendes retur til Spotnana UI. Det betyder, at brugeren nu er godkendt og kan tilgå Spotnana-platformen med dette token.
4	Når brugeren er godkendt i trin 3, skal alle efterfølgende API-kald indeholde bearer token, `orgId`og `tmcId` i anmodningshovedet. Bearer token bliver valideret ved alle indgående API-forespørgsler, og svaret sendes tilbage til Spotnana UI.

IdP-baseret godkendelse

Spotnana understøtter godkendelse via IdP’er som Google, Azure og egne IdP’er gennem OpenID Connect samt SAML-protokoller. Diagrammet og trinnene herunder forklarer, hvordan IdP-baseret godkendelse foregår.

Fig: Et sekvensdiagram, der forklarer IdP-baseret godkendelsesforløb.

Trin	Forløb
En bruger logger ind via OBT eller Spotnana-mobilappen med sin e-mailadresse.
1	Spotnana UI sender en API-forespørgsel til Spotnana-serveren for at hente godkendelsesoplysninger for brugeren. Forespørgslen indeholder brugerens loginoplysninger som parametre. Svaret indeholder brugerens `tmcId`, `orgId`, og `authProviderType`.
2	Spotnana UI viderestiller anmodningen til Spotnana IdP.
3	Spotnana IdP viderestiller anmodningen til partnerens IdP. Dette starter IdP-godkendelsen for brugeren. Bemærk: Ved hver viderestilling returneres statuskode 302 for at vise, at anmodningen er sendt videre til en anden URL.
4	Der oprettes forbindelse mellem Spotnana IdP og partnerens IdP. Denne forbindelse sikrer, at brugeren bliver godkendt af partnerens IdP. Bemærk: Under denne forbindelse sender Spotnana IdP `clientId` og `clientSecret` som URL-kodede data via et API-kald til partnerens IdP. Hvis IdP-serverne ikke kan håndtere dette dataformat, kan Spotnana-serveren fungere som mellemled og oversætte dataene til et format, partnerens IdP kan forstå.
5	Partnerens IdP godkender brugeren. Bemærk: Efter dette trin skal brugerprofilen stadig gennemgå validering af bearer token.
5 a	Når godkendelsen er gennemført, sender partnerens IdP et svar tilbage til Spotnana IdP.
5 b	Spotnana IdP opretter en unik kode til brugerprofilen og sender den til Spotnana UI.
6	Spotnana UI sender en API-forespørgsel til Spotnana IdP med `clientID` og den kode, der blev modtaget i trin 5(b). Spotnana IdP opretter et nyt bearer token og sender det til Spotnana UI. Bemærk: At der bliver oprettet et bearer token, betyder, at brugeren nu er godkendt og har adgang til Spotnana.
7	Når brugeren er godkendt i trin 6, skal alle efterfølgende API-kald indeholde bearer token, `orgId`og `tmcId` i anmodningshovedet. Bearer token bliver valideret ved alle indgående API-forespørgsler, og svaret sendes tilbage til Spotnana UI.

API-baseret godkendelse

Partnere, der bruger Spotnanas API’er til at forbinde sig til platformen, kan bruge vores godkendelses-endpoint til at generere et bearer token til deres brugere. Sekvensdiagrammet herunder viser, hvordan godkendelsesforløbet ser ud for partnere, der benytter API-baseret godkendelse.

Fig: Et sekvensdiagram, der forklarer API-baseret godkendelse.

Trin Forløb

Trin	Forløb
1	API-brugeren laver et POST kald til `get-auth-token(clientId,clientSecret)` API-endpointet på Spotnana-serveren for at oprette og hente et midlertidigt bearer token. Her er et eksempel på en cUrl-forespørgsel, du kan bruge, når du kalder `get-auth-token` endpointet: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Bemærk: Udskift værdierne for `clientId` og `clientSecret` med de oplysninger, du har modtaget fra Spotnana.
2	Spotnana-serveren kalder metoden `getToken(clientId,clientSecret)` i Spotnana IdP, som opretter et midlertidigt `bearerToken` og sender det tilbage til Spotnana-serveren. Spotnana-serveren sender dette bearer token som et JSON-svar til API-brugeren.

API-brugeren laver et POST kald til get-auth-token(clientId,clientSecret) API-endpointet på Spotnana-serveren for at oprette og hente et midlertidigt bearer token.

Her er et eksempel på en cUrl-forespørgsel, du kan bruge, når du kalder get-auth-token endpointet:

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

Bemærk: Udskift værdierne for clientId og clientSecret med de oplysninger, du har modtaget fra Spotnana.

Spotnana-serveren kalder metoden getToken(clientId,clientSecret) i Spotnana IdP, som opretter et midlertidigt bearerToken og sender det tilbage til Spotnana-serveren.
Spotnana-serveren sender dette bearer token som et JSON-svar til API-brugeren.

Når API-brugeren har modtaget bearer token, skal alle efterfølgende forespørgsler til Spotnana API’er (f.eks. Trip APIs) indeholde bearer token i headeren for at få adgang.

Bemærk: Endpointet get-auth-token(clientId, clientSecret) har en grænse på 100 API-kald pr. 5 minutter.

iFrame-baseret godkendelse

En iFrame- eller indlejret løsning betyder, at partnerne integrerer Spotnana UI direkte i deres egen brugergrænseflade, så brugerne tilgår Spotnana gennem partnerens UI. I dette tilfælde sker brugerens godkendelse ved, at der udveksles tokens mellem partnerens og Spotnanas systemer.

Bemærk: Ved iFrame-baseret godkendelse omtales brugeren, der logger ind, som en caller. Dette gør det muligt at håndtere situationer, hvor en API- eller maskinebruger logger ind og anmoder om et access token på vegne af en anden bruger. Denne API- eller maskinebruger kan f.eks. bruge TMC-adminkontoen til at forbinde sig direkte til Spotnana-serveren. Derfor bruger vi caller som en generel betegnelse, der både kan dække brugere, der logger ind på deres egen profil, og API-/maskinebrugere, der anmoder om access token på vegne af andre.

Sekvensdiagrammet herunder viser, hvordan godkendelsesforløbet håndteres via token-udveksling mellem Spotnana og partnerens servere.

Fig: Et sekvensdiagram, der forklarer iFrame-baseret godkendelse med token-udveksling.

Trin	Forløb
En caller logger ind via partnerens brugergrænseflade.
1	Partnerens UI viser Spotnana UI via en iFrame.
2	Spotnana UI sender en anmodning til partnerens UI via post message for at hente tokens. Anmodningen sendes med `type=TOKEN_EXCHANGE_REQUEST`.
3	Partnerens UI sender en API-forespørgsel til partnerens server for at hente OAuth-token og starter de næste trin i godkendelsesforløbet.
3 a	Partnerens server kalder Spotnana-serveren med brugeroplysninger og subject token som parametre. Spotnana-serveren tjekker, om forespørgslen kommer fra en API-/maskinebruger.
3 b	Spotnana-serveren kontakter partnerens server for at hente subject (altså callerens) e-mail. E-mailen hentes og sendes til Spotnana-serveren, som bruger den til at identificere brugeren.
3 c	Spotnana-serveren sender svaret på API-forespørgslen fra trin 1 til partnerens server med access token og refresh token. Disse detaljer sendes herefter videre til partnerens UI.
4	Partnerens UI sender token videre til Spotnana UI via post message med `type=TOKEN_EXCHANGE_RESPONSE.`
5	Spotnana UI sender en API-forespørgsel til Spotnana-serveren for at oprette og hente et nyt bearer token. Spotnana-serveren opretter et bearer token og sender det retur til Spotnana UI. Bemærk: At der bliver oprettet et bearer token, betyder, at brugeren nu er godkendt og har adgang til Spotnana.
6	Når brugeren er godkendt i trin 3, skal alle efterfølgende API-kald indeholde bearer token, `orgId`og `tmcId` i anmodningshovedet. Bearer token bliver valideret ved alle indgående API-forespørgsler, og svaret sendes tilbage til Spotnana UI.

Godkendelse med autorisationskode

Sekvensdiagrammet herunder viser, hvordan godkendelsesforløbet håndteres med en autorisationskode.

Fig: Et sekvensdiagram, der forklarer godkendelse med autorisationskode.

Trin	Forløb
1	Partnerens UI kalder partnerens server for at hente en autorisationskode til den caller, der logger ind. Koden hentes og sendes tilbage til partnerens UI.
2	Partnerens UI sender en anmodning til Spotnana UI via en tilpasset redirect-URL, hvor `tmcId` og `authCode` er parametre.
3	Spotnana UI laver et POST API-kald til Spotnana-serveren med `v2/auth/token/companies/<tmcId>(authCode)` API-endpointet.
3 a	Spotnana-serveren sender en anmodning til partnerens server for at hente brugerens `pid` ved hjælp af autorisationskoden. Brugerens `pid` hentes og sendes til Spotnana-serveren.
3 b	Access token og refresh token oprettes af Spotnana-serveren og sendes til Spotnana UI.
4	Spotnana UI sender en anmodning til Spotnana-serveren med access token og refresh token for at oprette og hente et bearer token til adgang. Et bearer token oprettes og sendes til Spotnana UI. Bemærk: At der bliver oprettet et bearer token, betyder, at brugeren nu er godkendt og har adgang til Spotnana.
5	Når brugeren er godkendt i trin 4, skal alle efterfølgende API-kald indeholde bearer token, `orgId`og `tmcId` i anmodningshovedet. Bearer token bliver valideret ved alle indgående API-forespørgsler, og svaret sendes tilbage til Spotnana UI.

Bemærk: Dette godkendelsesforløb kan ikke bruges, hvis en TMC-administrator tillader, at flere brugere logger ind med samme e-mail.

Maskine-til-maskine (M2M) godkendelse

M2M-godkendelsesmetoden er velegnet, når forløbet kræver, at klientapplikationen tilgår en tredjeparts callback-URL for at oprette accessToken til brugeren. Sekvensdiagrammet herunder viser, hvordan M2M-godkendelsen foregår.

Fig: Et sekvensdiagram, der forklarer M2M-godkendelsesforløbet.

Trin	Forløb
De offentlige nøgler for alle applikationer, der bruges i godkendelsen, synkroniseres mellem Spotnana-serveren og Spotnana IdP. Disse bruges senere til at verificere access token i forløbet.
1	Partnerens server sender en API-forespørgsel til `/oauth2/token(clientId,clientSecret)` i Spotnana IdP for at oprette et bearer token. Det nye bearer token sendes retur til partnerens server.
2	Partnerens server sender en API-forespørgsel til en tredjeparts callback-URL for at oprette et access token til brugeren. Dette access token oprettes og sendes til Spotnana-serveren.
3	Spotnana-serveren validerer access token-signaturen med de tidligere synkroniserede offentlige nøgler. Den validerer også `claim_id` som bekræfter partnerens identitet. Access token sendes herefter til partnerens server for at godkende brugeren.