Überblick über die Authentifizierungsprozesse bei Spotnana

Erstellt von Ashish Chaudhary, Geändert am Sa, 4 Okt um 2:31 VORMITTAGS von Ashish Chaudhary

Spotnana-Authentifizierungsprozesse – Übersicht

INHALTSVERZEICHNIS

Spotnana-Authentifizierungsprozesse – Übersicht
- Zentrale Komponenten
- Unterstützte Authentifizierungsmethoden

Spotnana stellt verschiedene Authentifizierungsmethoden bereit, mit denen Partner eine sichere Integration mit unserer Plattform umsetzen können. In dieser Dokumentation finden Sie eine Übersicht der aktuell unterstützten Authentifizierungsverfahren bei Spotnana sowie detaillierte Beschreibungen der jeweiligen Abläufe. Die hier aufgeführten Authentifizierungsprozesse zeigen, wie Spotnana Nutzer authentifiziert und berechtigt, um auf geschützte, unternehmensspezifische Ressourcen zuzugreifen – also auf die Ressourcen, die dem Unternehmen des Nutzers auf der Spotnana-Plattform gehören.

Zentrale Komponenten

Bevor Sie loslegen, werfen Sie bitte einen Blick auf diese Liste mit den wichtigsten Systemkomponenten, auf die in dieser Dokumentation Bezug genommen wird.

Spotnana UI(Spotnana Benutzeroberfläche) Bezieht sich auf die Spotnana-Frontend-Webanwendung (also das Online-Buchungstool) oder die Spotnana-Mobile-App. Konkret ist damit die Anmeldeseite gemeint, über die beim Login oder bei der Erstellung eines neuen Kontos der Authentifizierungsprozess im Frontend gestartet wird.
Spotnana-Server Bezeichnet den Spotnana-Backend-Server, der für Authentifizierungszwecke genutzt wird – also etwa für die Autorisierung eines Nutzers zum Zugriff auf Ressourcen und für die sichere Speicherung und Verarbeitung von Nutzerinformationen.
Partner UI (Benutzeroberfläche des Partners) Die Benutzeroberfläche (also die Frontend-Anwendung), die von Partnern genutzt wird, um auf die Spotnana-Plattform zuzugreifen. Beim iFrame-basierten Authentifizierungsverfahren wird beispielsweise die Spotnana-Plattform direkt in die Benutzeroberfläche des Partners eingebettet, sodass dessen Nutzer Spotnana über diese Oberfläche verwenden.
Partner-Server Bezieht sich auf einen oder mehrere Backend-Server, die unsere Partner für die Integration mit Spotnana einsetzen.
Spotnana IdP (Spotnana Identity Provider) Bezeichnet den internen Spotnana-Service für Identitätsmanagement und Autorisierung von Nutzern.
Partner IdP Drittanbieter-Identity-Provider (IdP), die von unseren Partnern genutzt werden. Häufig verwendete IdPs sind zum Beispiel Google oder Azure.
OBT Spotnanas Online-Buchungstool (OBT), erreichbar unter https://app.spotnana.com/
Subject Token Beim iFrame-basierten (bzw. Token-Exchange-) Authentifizierungsverfahren steht das Subject Token für die Identität des Nutzers. Mit diesem Token werden die Nutzerdaten abgerufen und die Berechtigung für den Zugriff auf die Spotnana-Plattform geprüft.
Access Token Ein OAuth-Zugangstoken, mit dem eine Partneranwendung im Namen eines Nutzers geschützte Ressourcen abrufen kann. Es handelt sich um einen temporären Autorisierungsschlüssel, der es Anwendungen ermöglicht, API-Anfragen zu stellen, ohne die Zugangsdaten des Nutzers preiszugeben.
Refresh Token Ein langlebiges Token, mit dem neue Access Tokens angefordert werden können, ohne dass sich der Nutzer erneut anmelden muss. Dieses Token wird in der Regel zusammen mit dem Access Token beim ersten Login ausgegeben.
Client-Zugangsdaten Die Zugangsdaten für Nutzer, die direkt mit den Spotnana-APIs arbeiten (also eine eindeutige clientId und clientSecret).
PID (Persönlicher Identifikator) Ein individueller Identifikator, der für den Nutzer erstellt wird. Die PID wird verwendet, um die Nutzerdaten vom Spotnana-Server abzurufen.
orgId Eine von Spotnana vergebene eindeutige Kennung für die Organisation des Nutzers.
tmcId Eine von Spotnana vergebene eindeutige Kennung für ein TMC (Travel Management Company).

Unterstützte Authentifizierungsmethoden

Spotnana unterstützt die folgenden Authentifizierungsmethoden:

Passwortbasierte Authentifizierung
- Bestehender Nutzer
- Neuer Nutzer
IdP-basierte Authentifizierung
API-basierte Authentifizierung
iFrame-basierte Authentifizierung
Authentifizierung per Autorisierungscode
Maschine-zu-Maschine (M2M) Authentifizierung

Passwortbasierte Authentifizierung

Bei der passwortbasierten Authentifizierung startet und steuert die Spotnana UI (also die Login- oder Registrierungsseite im OBT) den Authentifizierungsprozess mit den Spotnana-Backend-Servern. Je nachdem, ob ein Nutzer sich mit einem bestehenden Profil anmeldet oder ein neues Profil anlegt, gibt es zwei unterschiedliche Abläufe. Beide Varianten werden in den folgenden Abschnitten anhand von Ablaufdiagrammen erläutert.

Bestehender Nutzer

Das folgende Ablaufdiagramm und die dazugehörigen Schritte zeigen, wie die Spotnana UI mit den Backend-Diensten zusammenarbeitet, um einen bestehenden Nutzer zu authentifizieren.

Abb.: Ablaufdiagramm zur passwortbasierten Authentifizierung für bestehende Nutzer.

Schritt	Ablauf
Ein bestehender Nutzer meldet sich über das OBT oder die Spotnana-App mit seiner E-Mail-Adresse an.
1	Die Spotnana UI sendet eine API-Anfrage an den Spotnana-Server, um die Authentifizierungskonfiguration für den Nutzer abzurufen. Die Anfrage enthält die Login-Daten des Nutzers als Parameter. Die Antwort enthält die `tmcId`, `orgId`und den `authProviderType`des Nutzers.
2	Die Spotnana UI sendet eine API-Anfrage an den Spotnana IdP mit `clientId`, E-Mail und Passwort. Der Spotnana IdP erstellt daraufhin ein neues Bearer-Token und gibt es an die Spotnana UI zurück. Damit ist der Nutzer authentifiziert.
3	Sobald der Nutzer in Schritt 2 authentifiziert wurde, müssen alle weiteren API-Anfragen das Bearer-Token, die `orgId`und die `tmcId` im Anfrage-Header enthalten. Das Bearer-Token wird bei allen eingehenden API-Anfragen geprüft und die Antwort an die Spotnana UI zurückgegeben.

Neuer Nutzer

Das folgende Ablaufdiagramm und die Schritte zeigen, wie die Spotnana UI mit den Backend-Diensten zusammenarbeitet, um einen neuen Nutzer (oder einen Nutzer, der sein Passwort zurücksetzen möchte) zu authentifizieren.

Abb.: Ablaufdiagramm zur passwortbasierten Authentifizierung für neue Nutzer.

Schritt	Ablauf
Ein neuer Nutzer gibt seine E-Mail-Adresse auf der Login-Seite des Spotnana OBT ein und klickt auf Weiter.
1	Die Spotnana UI sendet eine API-Anfrage an den Spotnana-Server, um die Authentifizierungskonfiguration für den Nutzer abzurufen. Die Anfrage enthält die Login-Daten des Nutzers als Parameter. Die Antwort enthält die `tmcId`, `orgId`und den `authProviderType`des Nutzers.
1 a	Der Nutzer legt ein neues Passwort fest und klickt auf Weiter.
2	Die Spotnana UI sendet eine API-Anfrage an den Spotnana IdP, um den Nutzer mit `clientId`, E-Mail und neuem Passwort zu registrieren. Nach erfolgreicher Registrierung wird ein Einmalpasswort (OTP) an die E-Mail-Adresse des Nutzers gesendet.
3	Der Nutzer gibt das OTP in der Spotnana UI ein und klickt auf Bestätigen. Die Spotnana UI sendet eine Anfrage an den Spotnana IdP, um das OTP zu prüfen und ein Bearer-Token für den Login zu erzeugen. Das Bearer-Token wird erstellt und an die Spotnana UI zurückgegeben. Damit ist der Nutzer erfolgreich authentifiziert und kann mit dem Bearer-Token auf die Spotnana-Plattform zugreifen.
4	Sobald der Nutzer in Schritt 3 authentifiziert wurde, müssen alle weiteren API-Anfragen das Bearer-Token, die `orgId`und die `tmcId` im Anfrage-Header enthalten. Das Bearer-Token wird bei allen eingehenden API-Anfragen geprüft und die Antwort an die Spotnana UI zurückgegeben.

IdP-basierte Authentifizierung

Spotnana unterstützt die Authentifizierung über IdPs wie Google, Azure und eigene IdPs via OpenID Connect sowie SAML-Protokolle. Das folgende Ablaufdiagramm und die dazugehörigen Schritte zeigen, wie die IdP-basierte Authentifizierung abläuft.

Abb.: Ablaufdiagramm zur IdP-basierten Authentifizierung.

Schritt	Ablauf
Ein Nutzer meldet sich über das OBT oder die Spotnana-App mit seiner E-Mail-Adresse an.
1	Die Spotnana UI sendet eine API-Anfrage an den Spotnana-Server, um die Authentifizierungskonfiguration für den Nutzer abzurufen. Die Anfrage enthält die Login-Daten des Nutzers als Parameter. Die Antwort enthält die `tmcId`, `orgId`und den `authProviderType`des Nutzers.
2	Die Spotnana UI leitet die Anfrage an den Spotnana IdP weiter.
3	Der Spotnana IdP leitet die Anfrage an den IdP des Partners weiter. Damit wird die IdP-Authentifizierung für den Nutzer gestartet. Hinweis: Bei jeder Weiterleitung wird ein Statuscode 302 zurückgegeben, um anzuzeigen, dass die Anfrage auf eine andere URL umgeleitet wurde.
4	Zwischen dem Spotnana IdP und dem Partner-IdP wird eine Verbindung aufgebaut, um die Authentifizierung des Nutzers durch den Partner-IdP sicherzustellen. Hinweis: In diesem Schritt übermittelt der Spotnana IdP die `clientId` und `clientSecret` als URL-kodierte Daten per API-Aufruf an den Partner-IdP. Sollte das Datenformat vom IdP-Server nicht verarbeitet werden können, kann der Spotnana-Server als Proxy fungieren und das Format entsprechend anpassen.
5	Der Partner-IdP authentifiziert den Nutzer erfolgreich. Hinweis: Nach diesem Schritt muss das Nutzerprofil noch durch das Bearer-Token verifiziert werden.
5 a	Nach erfolgreicher Authentifizierung wird die Antwort vom Partner-IdP an den Spotnana IdP übermittelt.
5 b	Der Spotnana IdP erstellt einen eindeutigen Code für das Nutzerprofil und sendet diesen an die Spotnana UI.
6	Die Spotnana UI sendet eine API-Anfrage an den Spotnana IdP mit der `clientID` und dem in Schritt 5(b) erhaltenen Code. Der Spotnana IdP erstellt ein neues Bearer-Token und gibt es an die Spotnana UI zurück. Hinweis: Die erfolgreiche Erstellung des Bearer-Tokens zeigt an, dass der Nutzer authentifiziert ist und auf Spotnana zugreifen darf.
7	Sobald der Nutzer in Schritt 6 authentifiziert wurde, müssen alle weiteren API-Anfragen das Bearer-Token, die `orgId`und die `tmcId` im Anfrage-Header enthalten. Das Bearer-Token wird bei allen eingehenden API-Anfragen geprüft und die Antwort an die Spotnana UI zurückgegeben.

API-basierte Authentifizierung

Partner, die Spotnana-APIs nutzen, um sich mit der Spotnana-Plattform zu verbinden, können unseren Authentifizierungsendpunkt verwenden, um ein Bearer-Token für ihre Nutzer zu generieren. Das folgende Ablaufdiagramm zeigt, wie der Authentifizierungsprozess für Partner mit API-basierter Authentifizierung abläuft.

Abb.: Ablaufdiagramm zur API-basierten Authentifizierung.

Schritt Ablauf

Schritt	Ablauf
1	Der API-Nutzer sendet einen POST Aufruf an den `get-auth-token(clientId,clientSecret)` API-Endpunkt des Spotnana-Servers, um ein temporäres Bearer-Token zu generieren und abzurufen. Hier ein Beispiel für eine cURL-Anfrage an den `get-auth-token` Endpunkt: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Hinweis: Ersetzen Sie die Werte für `clientId` und `clientSecret` durch die Zugangsdaten, die Sie von Spotnana erhalten haben.
2	Der Spotnana-Server ruft die `getToken(clientId,clientSecret)` Methode im Spotnana IdP auf, wodurch ein temporäres `bearerToken` erstellt und an den Spotnana-Server zurückgegeben wird. Der Spotnana-Server gibt dieses Bearer-Token als JSON-Antwort an den API-Nutzer zurück.

Der API-Nutzer sendet einen POST Aufruf an den get-auth-token(clientId,clientSecret) API-Endpunkt des Spotnana-Servers, um ein temporäres Bearer-Token zu generieren und abzurufen.

Hier ein Beispiel für eine cURL-Anfrage an den get-auth-token Endpunkt:

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

Hinweis: Ersetzen Sie die Werte für clientId und clientSecret durch die Zugangsdaten, die Sie von Spotnana erhalten haben.

Der Spotnana-Server ruft die getToken(clientId,clientSecret) Methode im Spotnana IdP auf, wodurch ein temporäres bearerToken erstellt und an den Spotnana-Server zurückgegeben wird.
Der Spotnana-Server gibt dieses Bearer-Token als JSON-Antwort an den API-Nutzer zurück.

Sobald der API-Nutzer das Bearer-Token erhalten hat, müssen alle weiteren Anfragen an die Spotnana-APIs (z. B. Trip-APIs]) das Bearer-Token im Header für die Autorisierung enthalten.

Hinweis: Der get-auth-token(clientId, clientSecret) Endpunkt ist auf 100 API-Aufrufe pro 5 Minuten begrenzt.

iFrame-basierte Authentifizierung

Bei einer iFrame- oder eingebetteten Lösung wird die Spotnana UI direkt in die Partner UI eingebettet, sodass Nutzer Spotnana über die Oberfläche des Partners verwenden. In diesem Fall erfolgt die Authentifizierung des Nutzers über einen Token-Austausch zwischen dem Partner- und dem Spotnana-System.

Hinweis: Bei der iFrame-basierten Authentifizierung wird der sich anmeldende Nutzer als Callerbezeichnet. Das ist wichtig für Szenarien, in denen ein API-/Maschinen-Nutzer sich anmeldet und ein Zugriffstoken für eine andere Person anfordert. Ein solcher API-/Maschinen-Nutzer könnte z. B. TMC-Admin-Zugangsdaten nutzen, um direkt mit dem Spotnana-Server zu kommunizieren. Daher verwenden wir den Begriff Caller als Oberbegriff – das kann sowohl ein Nutzer sein, der sich in sein eigenes Profil einloggt, als auch ein API-/Maschinen-Nutzer, der ein Zugriffstoken für eine andere Person anfordert.

Das folgende Ablaufdiagramm zeigt, wie der Authentifizierungsprozess per Token-Austausch zwischen Spotnana- und Partner-Servern abläuft.

Abb.: Ablaufdiagramm zur iFrame-basierten Authentifizierung mittels Token-Austausch.

Schritt	Ablauf
Ein Caller meldet sich über die Partner UI an.
1	Die Partner UI stellt die Spotnana UI per iFrame dar.
2	Die Spotnana UI sendet eine Anfrage per Post-Message an die Partner UI, um Tokens anzufordern. Die Anfrage enthält `type=TOKEN_EXCHANGE_REQUEST`.
3	Die Partner UI sendet eine API-Anfrage an den Partner-Server, um das OAuth-Token abzurufen und startet so die nächsten Schritte im Authentifizierungsprozess.
3 a	Der Partner-Server ruft den Spotnana-Server mit den Zugangsdaten des Nutzers und dem Subject Token als Parameter auf. Der Spotnana-Server prüft, ob die Anfrage von einem API-/Maschinen-Nutzer stammt.
3 b	Der Spotnana-Server fragt beim Partner-Server die E-Mail-Adresse des Subjects (also des Callers) ab. Die E-Mail-Adresse wird abgerufen und an den Spotnana-Server zurückgegeben, um den Nutzer zu identifizieren.
3 c	Die Antwort auf die API-Anfrage aus Schritt 1 wird vom Spotnana-Server an den Partner-Server übermittelt und enthält das Access Token sowie das Refresh Token. Diese Informationen werden anschließend an die Partner UI weitergegeben.
4	Die Partner UI übermittelt das Token per Post-Message an die Spotnana UI mit `type=TOKEN_EXCHANGE_RESPONSE.`
5	Die Spotnana UI sendet eine API-Anfrage an den Spotnana-Server, um ein neues Bearer-Token zu generieren und abzurufen. Das Bearer-Token wird vom Spotnana-Server erstellt und an die Spotnana UI zurückgegeben. Hinweis: Mit der erfolgreichen Erstellung des Bearer-Tokens ist der Nutzer authentifiziert und kann auf Spotnana zugreifen.
6	Sobald der Nutzer in Schritt 3 authentifiziert wurde, müssen alle weiteren API-Anfragen das Bearer-Token, die `orgId`und die `tmcId` im Anfrage-Header enthalten. Das Bearer-Token wird bei allen eingehenden API-Anfragen geprüft und die Antwort an die Spotnana UI zurückgegeben.

Authentifizierung per Autorisierungscode

Das folgende Ablaufdiagramm zeigt, wie der Authentifizierungsprozess mit einem Autorisierungscode abläuft.

Abb.: Ablaufdiagramm zur Authentifizierung mit Autorisierungscode.

Schritt	Ablauf
1	Die Partner UI ruft beim Partner-Server den Autorisierungscode für den sich anmeldenden Caller ab. Der Code wird ermittelt und an die Partner UI zurückgegeben.
2	Die Partner UI sendet eine Anfrage mit einer benutzerdefinierten Redirect-URL an die Spotnana UI, die die `tmcId` und den `authCode` als Parameter enthält.
3	Die Spotnana UI führt einen POST API-Aufruf an den Spotnana-Server durch mit dem `v2/auth/token/companies/<tmcId>(authCode)` API-Endpunkt.
3 a	Der Spotnana-Server fragt beim Partner-Server die `pid` des Nutzers anhand des Autorisierungscodes ab. Die `pid` des Nutzers wird abgerufen und an den Spotnana-Server übermittelt.
3 b	Das Access Token und das Refresh Token werden vom Spotnana-Server generiert und an die Spotnana UI gesendet.
4	Die Spotnana UI sendet eine Anfrage an den Spotnana-Server, um mit Access Token und Refresh Token ein Bearer-Token für den Zugriff zu generieren und abzurufen. Das Bearer-Token wird erstellt und an die Spotnana UI gesendet. Hinweis: Mit der erfolgreichen Erstellung des Bearer-Tokens ist der Nutzer authentifiziert und kann auf Spotnana zugreifen.
5	Sobald der Nutzer in Schritt 4 authentifiziert wurde, müssen alle weiteren API-Anfragen das Bearer-Token, die `orgId`und die `tmcId` im Anfrage-Header enthalten. Das Bearer-Token wird bei allen eingehenden API-Anfragen geprüft und die Antwort an die Spotnana UI zurückgegeben.

Hinweis: Dieses Authentifizierungsverfahren kann nicht verwendet werden, wenn ein TMC-Admin mehreren Nutzern erlaubt, sich mit derselben E-Mail-Adresse anzumelden.

Maschine-zu-Maschine (M2M) Authentifizierung

Die M2M-Authentifizierung eignet sich für Szenarien, in denen die Client-Anwendung eine Drittanbieter-Callback-URL aufruft, um das accessToken für den Nutzer zu erzeugen. Das folgende Ablaufdiagramm zeigt den M2M-Authentifizierungsprozess.

Abb.: Ablaufdiagramm zum M2M-Authentifizierungsprozess.

Schritt	Ablauf
Die öffentlichen Schlüssel aller für die Authentifizierung verwendeten Anwendungen werden zwischen dem Spotnana-Server und dem Spotnana IdP synchronisiert. Diese Schlüssel werden später zur Prüfung des Access Tokens im Authentifizierungsprozess verwendet.
1	Der Partner-Server sendet eine API-Anfrage an `/oauth2/token(clientId,clientSecret)` im Spotnana IdP, um ein Bearer-Token zu generieren. Das neue Bearer-Token wird an den Partner-Server zurückgegeben.
2	Der Partner-Server sendet eine API-Anfrage an eine Drittanbieter-Callback-URL, um ein Access Token für den Nutzer zu generieren. Dieses Access Token wird erstellt und an den Spotnana-Server übermittelt.
3	Der Spotnana-Server prüft die Signatur des Access Tokens mit den zuvor synchronisierten öffentlichen Schlüsseln. Außerdem wird die `claim_id` überprüft, um die Identität des Partners zu bestätigen. Das Access Token wird anschließend an den Partner-Server übergeben, um den Nutzer zu authentifizieren.