Visió general dels processos d'autenticació de Spotnana

Creat per Ashish Chaudhary, Modificat el Ds, 4 Oct. a les 10:24 PM per Ashish Chaudhary

Visió general dels fluxos d'autenticació de Spotnana

ÍNDEX

Visió general dels fluxos d'autenticació de Spotnana
- Elements clau
- Mètodes d'autenticació admesos

Spotnana posa a disposició diversos mètodes d’autenticació perquè els seus col·laboradors puguin integrar-se de manera segura amb la nostra plataforma. En aquesta documentació hi trobareu una visió general dels diferents mètodes d’autenticació que Spotnana admet actualment, així com una explicació detallada de com funciona cada flux. Els diferents fluxos d’autenticació que es descriuen aquí mostren com Spotnana autentica i autoritza els usuaris per accedir als recursos protegits de l’organització (és a dir, els recursos que pertanyen a l’empresa de l’usuari dins la plataforma Spotnana).

Elements clau

Abans de començar, consulteu aquesta llista per veure la definició dels components essencials del sistema als quals es fa referència en aquesta documentació.

Interfície d’usuari de Spotnana (UI)(Interfície d’usuari de Spotnana) Fa referència a l’aplicació web de Spotnana (l’eina de reserves en línia) o a l’aplicació mòbil de Spotnana. En concret, es refereix a la pàgina d’inici de sessió, que és la que inicia el flux d’autenticació quan l’usuari accedeix o crea un nou compte.
Servidor de Spotnana Fa referència al servidor de backend de Spotnana utilitzat per a l’autenticació (per exemple, per autoritzar l’accés d’un usuari a un recurs o per emmagatzemar i processar la informació de l’usuari de manera segura).
Interfície d’usuari del col·laborador (Partner UI) (Interfície d’usuari del col·laborador) L’aplicació d’interfície d’usuari (frontend) que utilitzen els col·laboradors per accedir a la plataforma Spotnana. Per exemple, en el cas de l’autenticació mitjançant iFrame, la plataforma Spotnana s’insereix dins la interfície d’usuari del col·laborador i els seus usuaris hi accedeixen a través d’aquesta.
Servidor del col·laborador Fa referència a un o més servidors de backend que utilitzen els nostres col·laboradors per integrar-se amb Spotnana.
Spotnana IdP (Proveïdor d’identitat de Spotnana) És el servei intern de Spotnana destinat a la gestió d’identitats i autoritzacions d’usuaris.
IdP del col·laborador Proveïdors d’identitat (IdP) de tercers que utilitzen els col·laboradors. Alguns dels IdP més habituals són Google i Azure.
OBT Eina de reserves en línia (OBT) de Spotnana, accessible a https://app.spotnana.com/
Token de subjecte En l’autenticació mitjançant iFrame (o intercanvi de tokens), el token de subjecte representa la identitat de l’usuari. Aquest token s’utilitza per cercar la seva informació i autoritzar-ne l’accés a la plataforma Spotnana.
Token d’accés Una credencial (OAuth) que utilitza una aplicació de col·laborador per accedir a recursos protegits en nom d’un usuari. És una clau d’autorització temporal que permet fer peticions API sense exposar les credencials de l’usuari.
Token de renovació (refresh token) Una credencial de llarga durada que serveix per obtenir nous tokens d’accés sense que l’usuari hagi de tornar a autenticar-se. Normalment s’emet juntament amb el token d’accés quan l’usuari inicia sessió per primer cop.
Credencials de client La informació que es proporciona als usuaris que es connecten directament a les API de Spotnana (és a dir, un identificador clientId i clientSecretúnics).
PID (Identificador personal) Un identificador personal creat per a l’usuari. El PID permet recuperar la informació de l’usuari des del servidor de Spotnana.
orgId Identificador únic assignat per Spotnana a l’organització de l’usuari.
tmcId Identificador únic assignat per Spotnana a una TMC (Travel Management Company).

Mètodes d'autenticació admesos

Aquests són els diferents mètodes d’autenticació que Spotnana admet actualment:

Autenticació amb contrasenya
- Usuari existent
- Usuari nou
Autenticació basada en IdP
Autenticació mitjançant API
Autenticació mitjançant iFrame
Autenticació basada en codi d’autorització
Autenticació entre màquines (M2M)

Autenticació amb contrasenya

Quan s’utilitza l’autenticació amb contrasenya, la interfície d’usuari de Spotnana (la pàgina d’inici de sessió o de registre de l’OBT) inicia i gestiona el procés d’autenticació amb els servidors de backend de Spotnana. Aquest mètode pot seguir dos camins diferents segons si l’usuari accedeix amb un perfil ja existent o si es registra per crear-ne un de nou. A continuació s’expliquen cadascun d’aquests dos fluxos d’autenticació amb diagrames de seqüència.

Usuari existent

El diagrama de seqüència i els passos següents mostren com la interfície d’usuari de Spotnana interactua amb els serveis de backend per autenticar un usuari ja existent.

Figura: Diagrama de seqüència que explica l’autenticació amb contrasenya per a usuaris existents.

Pas	Flux
Un usuari existent inicia sessió a través de l’OBT o de l’aplicació mòbil de Spotnana utilitzant el seu correu electrònic.
1	La UI de Spotnana envia una petició API al servidor de Spotnana per recuperar la configuració d’autenticació de l’usuari. Aquesta petició inclou les credencials d’inici de sessió de l’usuari com a paràmetres. La resposta inclou el `tmcId`, `orgId`i el `authProviderType`de l’usuari.
2	La UI de Spotnana envia una petició API a Spotnana IdP amb el `clientId`, el correu electrònic i la contrasenya. Spotnana IdP genera un nou token bearer i el retorna a la UI de Spotnana. Amb aquest pas, l’usuari queda autenticat.
3	Un cop l’usuari ha estat autenticat al pas 2, totes les peticions API posteriors han d’incloure el token bearer, l’ `orgId`i el `tmcId` a l’encapçalament de la petició. El token bearer es valida en totes les peticions API entrants i la resposta es retorna a la UI de Spotnana.

Usuari nou

El diagrama de seqüència i els passos següents expliquen com la UI de Spotnana interactua amb els serveis de backend per autenticar un usuari nou (o un usuari existent que vol restablir la contrasenya).

Figura: Diagrama de seqüència que explica l’autenticació amb contrasenya per a usuaris nous.

Pas	Flux
Un usuari nou introdueix el seu correu electrònic a la pàgina d’inici de sessió de l’OBT de Spotnana i prem Següent.
1	La UI de Spotnana envia una petició API al servidor de Spotnana per recuperar la configuració d’autenticació de l’usuari. Aquesta petició inclou les credencials d’inici de sessió de l’usuari com a paràmetres. La resposta inclou el `tmcId`, `orgId`i el `authProviderType`de l’usuari.
1 a	L’usuari introdueix una nova contrasenya i prem Següent.
2	La UI de Spotnana envia una petició API a Spotnana IdP per registrar l’usuari juntament amb el seu `clientId`, correu electrònic i nova contrasenya. Un cop registrades les dades, s’envia una contrasenya d’un sol ús (OTP) al correu electrònic de l’usuari.
3	L’usuari introdueix l’OTP a la UI de Spotnana i prem Verifica. La UI de Spotnana envia una petició a Spotnana IdP per verificar l’OTP i generar un token bearer per iniciar la sessió. El token bearer es genera i es retorna a la UI de Spotnana. Això indica que l’autenticació de l’usuari s’ha completat correctament i ja pot accedir a la plataforma Spotnana amb aquest token.
4	Un cop l’usuari ha estat autenticat al pas 3, totes les peticions API posteriors han d’incloure el token bearer, l’ `orgId`i el `tmcId` a l’encapçalament de la petició. El token bearer es valida en totes les peticions API entrants i la resposta es retorna a la UI de Spotnana.

Autenticació basada en IdP

Spotnana permet l’autenticació a través d’IdPs com Google, Azure i IdPs personalitzats mitjançant OpenID Connect, així com protocols SAML. El diagrama de seqüència i els passos següents expliquen el flux d’autenticació basada en IdP.

Figura: Diagrama de seqüència que explica el flux d’autenticació basada en IdP.

Pas	Flux
Un usuari inicia sessió a través de l’OBT o de l’aplicació mòbil de Spotnana utilitzant el seu correu electrònic.
1	La UI de Spotnana envia una petició API al servidor de Spotnana per recuperar la configuració d’autenticació de l’usuari. Aquesta petició inclou les credencials d’inici de sessió de l’usuari com a paràmetres. La resposta inclou el `tmcId`, `orgId`i el `authProviderType`de l’usuari.
2	La UI de Spotnana redirigeix la petició a Spotnana IdP.
3	Spotnana IdP redirigeix la petició a l’IdP del col·laborador. Això inicia l’autenticació de l’usuari a través de l’IdP. Nota: A cada redirecció, es retorna un codi d’estat 302 per indicar que la petició s’ha redirigit a una altra URL.
4	Es crea una connexió entre Spotnana IdP i l’IdP del col·laborador per garantir que l’usuari s’autentica correctament a través de l’IdP del col·laborador. Nota: Durant aquesta connexió, Spotnana IdP envia el `clientId` i el `clientSecret` com a dades codificades per URL mitjançant una crida API a l’IdP del col·laborador. Si els servidors IdP no poden processar aquest format, el servidor de Spotnana pot actuar com a intermediari per traduir les dades al format que reconegui l’IdP del col·laborador.
5	L’IdP del col·laborador autentica l’usuari amb èxit. Nota: Un cop superat aquest pas, el perfil de l’usuari encara ha de passar la verificació del token bearer.
5 a	Després de l’autenticació, la resposta de l’IdP del col·laborador es retorna a Spotnana IdP.
5 b	Spotnana IdP genera un codi únic per al perfil de l’usuari i l’envia a la UI de Spotnana.
6	La UI de Spotnana envia una petició API a Spotnana IdP amb el `clientID` i el codi rebut al pas 5(b). Spotnana IdP genera un nou token bearer i l’envia a la UI de Spotnana. Nota: La creació correcta del token bearer indica que l’usuari ja està autenticat i pot accedir a Spotnana.
7	Un cop l’usuari ha estat autenticat al pas 6, totes les peticions API posteriors han d’incloure el token bearer, l’ `orgId`i el `tmcId` a l’encapçalament de la petició. El token bearer es valida en totes les peticions API entrants i la resposta es retorna a la UI de Spotnana.

Autenticació mitjançant API

Els col·laboradors que utilitzen les API de Spotnana per connectar-se a la plataforma poden utilitzar el nostre endpoint d’autenticació per generar un token bearer per als seus usuaris. El diagrama de seqüència següent mostra el flux d’autenticació per a qualsevol col·laborador que faci servir aquest mètode.

Figura: Diagrama de seqüència que explica l’autenticació mitjançant API.

Pas Flux

Pas	Flux
1	L’usuari de l’API fa una crida POST a l’endpoint `get-auth-token(clientId,clientSecret)` del servidor de Spotnana per generar i obtenir un token bearer temporal. A continuació teniu un exemple de com fer una petició cUrl a l’endpoint `get-auth-token` : curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Nota: Substituïu els valors de `clientId` i `clientSecret` per les credencials que us ha proporcionat Spotnana.
2	El servidor de Spotnana crida el mètode `getToken(clientId,clientSecret)` a Spotnana IdP, que genera un `bearerToken` temporal i el retorna al servidor de Spotnana. El servidor de Spotnana envia aquest token bearer com a resposta JSON a l’usuari de l’API.

L’usuari de l’API fa una crida POST a l’endpoint get-auth-token(clientId,clientSecret) del servidor de Spotnana per generar i obtenir un token bearer temporal.

A continuació teniu un exemple de com fer una petició cUrl a l’endpoint get-auth-token :

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

Nota: Substituïu els valors de clientId i clientSecret per les credencials que us ha proporcionat Spotnana.

El servidor de Spotnana crida el mètode getToken(clientId,clientSecret) a Spotnana IdP, que genera un bearerToken temporal i el retorna al servidor de Spotnana.
El servidor de Spotnana envia aquest token bearer com a resposta JSON a l’usuari de l’API.

Un cop l’usuari de l’API rep el token bearer, totes les peticions posteriors a les API de Spotnana (per exemple, Trip APIs) han d’incloure el token bearer a l’encapçalament per tal d’estar autoritzades.

Nota: L’endpoint get-auth-token(clientId, clientSecret) té un límit de 100 crides API cada 5 minuts.

Autenticació mitjançant iFrame

Una solució mitjançant iFrame o d’integració embeguda consisteix a incrustar la UI de Spotnana dins la UI del col·laborador, de manera que els usuaris accedeixen a Spotnana a través de la interfície del col·laborador. En aquest cas, l’autenticació de l’usuari es gestiona mitjançant l’intercanvi de tokens entre els sistemes del col·laborador i Spotnana.

Nota: En el cas de l’autenticació mitjançant iFrame, l’usuari que inicia sessió es denominarà caller. Això permet contemplar escenaris específics en què un usuari d’API o màquina inicia sessió i sol·licita un token d’accés per a un altre usuari. Aquest usuari d’API/màquina podria utilitzar credencials d’administrador de TMC per connectar-se directament amb el servidor de Spotnana. Per aquest motiu, utilitzarem el terme caller com a concepte general, tant per a un usuari que accedeix al seu propi perfil com per a un usuari d’API/màquina que sol·licita un token d’accés per a un altre usuari.

El diagrama de seqüència següent mostra com es gestiona el flux d’autenticació mitjançant l’intercanvi de tokens entre Spotnana i els servidors del col·laborador.

Figura: Diagrama de seqüència que explica l’autenticació mitjançant iFrame i intercanvi de tokens.

Pas	Flux
Un caller inicia sessió utilitzant la UI del col·laborador.
1	La UI del col·laborador mostra la UI de Spotnana mitjançant un iFrame.
2	La UI de Spotnana envia una petició a la UI del col·laborador mitjançant un missatge post per sol·licitar els tokens. Aquesta petició s’envia amb `type=TOKEN_EXCHANGE_REQUEST`.
3	La UI del col·laborador envia una petició API al servidor del col·laborador per obtenir el token OAuth, iniciant els següents passos consecutius del flux d’autenticació.
3 a	El servidor del col·laborador fa una crida al servidor de Spotnana utilitzant les credencials de l’usuari i el token de subjecte com a paràmetres. El servidor de Spotnana comprova si la petició prové d’un usuari d’API/màquina.
3 b	El servidor de Spotnana fa una crida al servidor del col·laborador per recuperar el correu electrònic del subjecte (és a dir, el caller). El correu electrònic es recupera i es retorna al servidor de Spotnana, que l’utilitza per identificar l’usuari.
3 c	La resposta a la petició API del pas 1 és enviada pel servidor de Spotnana al servidor del col·laborador amb el token d’accés i el token de renovació. Aquests detalls es fan arribar després a la UI del col·laborador.
4	La UI del col·laborador envia el token a la UI de Spotnana mitjançant un missatge post amb `type=TOKEN_EXCHANGE_RESPONSE.`
5	La UI de Spotnana envia una petició API al servidor de Spotnana per generar i obtenir un nou token bearer. El servidor de Spotnana genera el token bearer i el retorna a la UI de Spotnana. Nota: La creació correcta del token bearer indica que l’usuari ja està autenticat i pot accedir a Spotnana.
6	Un cop l’usuari ha estat autenticat al pas 3, totes les peticions API posteriors han d’incloure el token bearer, l’ `orgId`i el `tmcId` a l’encapçalament de la petició. El token bearer es valida en totes les peticions API entrants i la resposta es retorna a la UI de Spotnana.

Autenticació basada en codi d’autorització

El diagrama de seqüència següent mostra com es gestiona el flux d’autenticació mitjançant un codi d’autorització.

Figura: Diagrama de seqüència que explica l’autenticació basada en codi d’autorització.

Pas	Flux
1	La UI del col·laborador crida el servidor del col·laborador per obtenir el codi d’autorització per al caller que inicia sessió. El codi s’obté i es retorna a la UI del col·laborador.
2	La UI del col·laborador envia una petició a la UI de Spotnana utilitzant una URL de redirecció personalitzada que inclou el `tmcId` i l’ `authCode` com a paràmetres.
3	La UI de Spotnana fa una crida POST a l’API de Spotnana utilitzant l’endpoint `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	El servidor de Spotnana fa una petició al servidor del col·laborador per obtenir el `pid` de l’usuari mitjançant el codi d’autorització. El `pid` de l’usuari es recupera i s’envia al servidor de Spotnana.
3 b	El token d’accés i el token de renovació es generen al servidor de Spotnana i es retornen a la UI de Spotnana.
4	La UI de Spotnana envia una petició al servidor de Spotnana amb el token d’accés i el token de renovació per generar i obtenir un token bearer d’accés. El token bearer es genera i s’envia a la UI de Spotnana. Nota: La creació correcta del token bearer indica que l’usuari ja està autenticat i pot accedir a Spotnana.
5	Un cop l’usuari ha estat autenticat al pas 4, totes les peticions API posteriors han d’incloure el token bearer, l’ `orgId`i el `tmcId` a l’encapçalament de la petició. El token bearer es valida en totes les peticions API entrants i la resposta es retorna a la UI de Spotnana.

Nota: Aquest flux d’autenticació no es pot utilitzar en casos en què un administrador de TMC permet que més d’un usuari iniciï sessió amb el mateix correu electrònic.

Autenticació entre màquines (M2M)

El mètode d’autenticació M2M és adequat quan el flux d’autenticació implica que l’aplicació client accedeixi a una URL de callback de tercers per generar l’ accessToken per a l’usuari. El diagrama de seqüència següent mostra el flux d’autenticació M2M.

Figura: Diagrama de seqüència que explica el flux d’autenticació M2M.

Pas	Flux
Les claus públiques de totes les aplicacions utilitzades en l’autenticació es sincronitzen entre el servidor de Spotnana i Spotnana IdP. Aquestes claus es faran servir després per verificar el token d’accés durant el flux d’autenticació.
1	El servidor del col·laborador envia una petició API a `/oauth2/token(clientId,clientSecret)` a Spotnana IdP per generar un token bearer. El nou token bearer es retorna al servidor del col·laborador.
2	El servidor del col·laborador envia una petició API a una URL de callback de tercers per generar un token d’accés per a l’usuari. Aquest token d’accés es crea i s’envia al servidor de Spotnana.
3	El servidor de Spotnana valida la signatura del token d’accés utilitzant les claus públiques sincronitzades prèviament. També valida el `claim_id` per verificar la identitat del col·laborador. El token d’accés es retorna al servidor del col·laborador per autenticar l’usuari.