Resumen de los métodos de autenticación en Spotnana

Creada por Ashish Chaudhary, Modificado el Dom., 5 Oct. a las 6:53 P. M. por Ashish Chaudhary

Flujos de autenticación de Spotnana - Descripción general

TABLA DE CONTENIDOS

Flujos de autenticación de Spotnana - Descripción general
- Componentes clave
- Métodos de autenticación compatibles

Spotnana ofrece diferentes métodos de autenticación para que nuestros socios puedan integrarse de manera segura con nuestra plataforma. En esta documentación encontrarás un resumen de los métodos de autenticación que actualmente soporta Spotnana, junto con explicaciones detalladas sobre cómo funciona cada flujo. Los distintos flujos de autenticación aquí mencionados muestran cómo Spotnana valida y autoriza a los usuarios para que puedan acceder a los recursos protegidos a nivel organizacional (es decir, los recursos que pertenecen a la empresa del usuario dentro de la plataforma de Spotnana).

Componentes clave

Antes de comenzar, revisa este listado para conocer las definiciones de los componentes esenciales del sistema que se mencionan en esta documentación.

Interfaz de usuario de Spotnana (Spotnana UI)(Interfaz de usuario de Spotnana) Hace referencia a la aplicación web de Spotnana (es decir, la herramienta de reservas en línea) o a la app móvil de Spotnana. Más específicamente, se refiere a la página de inicio de sesión, que es la que inicia el flujo de autenticación cuando el usuario entra o crea una cuenta nueva.
Servidor de Spotnana Se refiere al servidor backend de Spotnana que se utiliza para autenticación (por ejemplo, para autorizar a un usuario a acceder a un recurso y para almacenar y procesar la información del usuario de forma segura).
Interfaz de usuario del socio (Partner UI) (Interfaz de usuario del socio) Es la interfaz (o aplicación web) que utilizan los socios para acceder a la plataforma de Spotnana. Por ejemplo, en la autenticación vía iFrame, la plataforma de Spotnana se integra dentro de la interfaz del socio y sus usuarios acceden a Spotnana a través de esa interfaz.
Servidor del socio Hace referencia a uno o varios servidores backend que utilizan nuestros socios para integrarse con Spotnana.
Spotnana IdP (Proveedor de Identidad de Spotnana) Se refiere al servicio interno de Spotnana utilizado para la gestión de identidades y autorización de usuarios.
IdP del socio Proveedores de identidad de terceros (IdP) que utilizan los socios. Algunos ejemplos comunes son Google y Azure.
OBT La herramienta de reservas en línea de Spotnana (OBT), a la que puedes acceder en https://app.spotnana.com/
Token de sujeto En la autenticación vía iFrame (o intercambio de tokens), el token de sujeto representa la identidad del usuario. Este token se utiliza para consultar su información y autorizar el acceso a la plataforma Spotnana.
Token de acceso Es una credencial (OAuth) que usa una aplicación socia para acceder a recursos protegidos en nombre de un usuario. Es una clave temporal de autorización que permite a las aplicaciones hacer solicitudes a la API sin exponer las credenciales del usuario.
Token de actualización Es una credencial de larga duración que sirve para obtener nuevos tokens de acceso sin que el usuario tenga que volver a autenticarse. Normalmente se emite junto con el token de acceso cuando el usuario inicia sesión por primera vez.
Credenciales de cliente La información que se entrega a los usuarios que se conectan directamente a las APIs de Spotnana (es decir, un clientId y clientSecret).
PID (Identificador personal) Un identificador personal creado para el usuario. El PID permite recuperar la información del usuario desde el servidor de Spotnana.
orgId Identificador único que Spotnana asigna a la organización del usuario.
tmcId Identificador único que Spotnana asigna a una TMC (Travel Management Company).

Métodos de autenticación compatibles

A continuación te mostramos los diferentes métodos de autenticación que puedes usar con Spotnana:

Autenticación con contraseña
- Usuario existente
- Usuario nuevo
Autenticación basada en IdP
Autenticación vía API
Autenticación vía iFrame
Autenticación basada en código de autorización
Autenticación máquina a máquina (M2M)

Autenticación con contraseña

Cuando se utiliza la autenticación por contraseña, la interfaz de Spotnana (es decir, la página de inicio de sesión o registro en el OBT) es la que inicia y gestiona el proceso de autenticación con los servidores backend de Spotnana. Este método puede tener dos flujos distintos, dependiendo de si el usuario inicia sesión con un perfil ya existente o si se está registrando como nuevo usuario. A continuación, te explicamos ambos flujos con diagramas de secuencia.

Usuario existente

El diagrama de secuencia y los pasos que verás a continuación muestran cómo la interfaz de Spotnana interactúa con los servicios backend para autenticar a un usuario que ya tiene cuenta.

Fig: Diagrama de secuencia que explica la autenticación con contraseña para usuarios existentes.

Paso	Flujo
Un usuario existente inicia sesión en el OBT o en la app móvil de Spotnana usando su correo electrónico.
1	La interfaz de Spotnana envía una solicitud API al servidor de Spotnana para obtener la configuración de autenticación del usuario. La solicitud incluye las credenciales de inicio de sesión del usuario como parámetros. La respuesta contiene el `tmcId`, `orgId`y el `authProviderType`del usuario.
2	La interfaz de Spotnana envía una solicitud API al Spotnana IdP usando el `clientId`, el correo electrónico y la contraseña. El Spotnana IdP genera un nuevo bearer token y lo devuelve a la interfaz de Spotnana. En este paso se autentica al usuario.
3	Una vez autenticado el usuario en el paso 2, todas las siguientes solicitudes API deben incluir el bearer token, el `orgId`y el `tmcId` en el encabezado de la solicitud. El bearer token se valida en todas las solicitudes API entrantes y la respuesta se envía de regreso a la interfaz de Spotnana.

Usuario nuevo

El diagrama de secuencia y los pasos siguientes muestran cómo la interfaz de Spotnana interactúa con los servicios backend para autenticar a un usuario nuevo (o a un usuario existente que está intentando restablecer su contraseña).

Fig: Diagrama de secuencia que explica la autenticación con contraseña para usuarios nuevos.

Paso	Flujo
Un usuario nuevo ingresa su correo electrónico en la página de inicio de sesión del OBT de Spotnana y hace clic en Siguiente.
1	La interfaz de Spotnana envía una solicitud API al servidor de Spotnana para obtener la configuración de autenticación del usuario. La solicitud incluye las credenciales de inicio de sesión del usuario como parámetros. La respuesta contiene el `tmcId`, `orgId`y el `authProviderType`del usuario.
1 a	El usuario ingresa una nueva contraseña y hace clic en Siguiente.
2	La interfaz de Spotnana envía una solicitud API al Spotnana IdP para registrar al usuario junto con su `clientId`, correo electrónico y la nueva contraseña. Después de registrar los datos, se envía una contraseña de un solo uso (OTP) al correo del usuario.
3	El usuario ingresa el OTP en la interfaz de Spotnana y hace clic en Verificar. La interfaz de Spotnana envía una solicitud al Spotnana IdP para verificar el OTP y generar un bearer token para el inicio de sesión. El bearer token se genera y se envía a la interfaz de Spotnana. Esto indica que el usuario fue autenticado exitosamente y puede acceder a la plataforma de Spotnana usando el bearer token.
4	Una vez autenticado el usuario en el paso 3, todas las siguientes solicitudes API deben incluir el bearer token, el `orgId`y el `tmcId` en el encabezado de la solicitud. El bearer token se valida en todas las solicitudes API entrantes y la respuesta se envía de regreso a la interfaz de Spotnana.

Autenticación basada en IdP

Spotnana permite autenticarse usando IdPs como Google, Azure y otros IdPs personalizados a través de OpenID Connect, así como protocolos SAML. El diagrama de secuencia y los pasos a continuación explican cómo funciona este flujo de autenticación.

Fig: Diagrama de secuencia que explica el flujo de autenticación basado en IdP.

Paso	Flujo
Un usuario inicia sesión en el OBT o en la app móvil de Spotnana usando su correo electrónico.
1	La interfaz de Spotnana envía una solicitud API al servidor de Spotnana para obtener la configuración de autenticación del usuario. La solicitud incluye las credenciales de inicio de sesión del usuario como parámetros. La respuesta contiene el `tmcId`, `orgId`y el `authProviderType`del usuario.
2	La interfaz de Spotnana redirige la solicitud al Spotnana IdP.
3	El Spotnana IdP redirige la solicitud al IdP del socio. Esto inicia la autenticación en el IdP del socio para el usuario. Nota: En cada redirección, se devuelve un código de estado 302 para indicar que la solicitud fue redirigida a otra URL.
4	Se establece una conexión entre el Spotnana IdP y el IdP del socio. Esta conexión sirve para asegurar que el usuario sea autenticado por el IdP del socio. Nota: Durante esta conexión, el Spotnana IdP envía el `clientId` y el `clientSecret` como datos codificados en formato URL usando una llamada API al IdP del socio. Si los servidores IdP no pueden procesar este formato, el servidor de Spotnana puede actuar como intermediario para traducir los datos a un formato que el IdP del socio reconozca.
5	El IdP del socio autentica exitosamente al usuario. Nota: Después de este paso, el perfil del usuario aún debe pasar por la verificación del bearer token.
5 a	Tras la autenticación exitosa, la respuesta del IdP del socio se envía al Spotnana IdP.
5 b	El Spotnana IdP genera un código único para el perfil del usuario y lo envía a la interfaz de Spotnana.
6	La interfaz de Spotnana envía una solicitud API al Spotnana IdP usando el `clientID` y el código recibido en el paso 5(b). El Spotnana IdP genera un nuevo bearer token y lo envía a la interfaz de Spotnana. Nota: La creación exitosa del bearer token indica que el usuario ya está autenticado y puede acceder a Spotnana.
7	Una vez autenticado el usuario en el paso 6, todas las siguientes solicitudes API deben incluir el bearer token, el `orgId`y el `tmcId` en el encabezado de la solicitud. El bearer token se valida en todas las solicitudes API entrantes y la respuesta se envía de regreso a la interfaz de Spotnana.

Autenticación vía API

Los socios que usan las APIs de Spotnana para conectarse a la plataforma pueden utilizar nuestro endpoint de autenticación para generar un bearer token para sus usuarios. El siguiente diagrama de secuencia muestra cómo funciona el flujo de autenticación para cualquier socio que utilice autenticación vía API.

Fig: Diagrama de secuencia que explica la autenticación vía API.

Paso Flujo

Paso	Flujo
1	El usuario de la API realiza una llamada POST a la endpoint `get-auth-token(clientId,clientSecret)` en el servidor de Spotnana para generar y obtener un bearer token temporal. Aquí tienes un ejemplo de solicitud cUrl que puedes usar para llamar al 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: Reemplaza los valores de `clientId` y `clientSecret` por las credenciales que recibiste de Spotnana.
2	El servidor de Spotnana llama al método `getToken(clientId,clientSecret)` en el Spotnana IdP, que genera un `bearerToken` temporal y lo envía de regreso al servidor de Spotnana. El servidor de Spotnana envía este bearer token como respuesta en formato JSON al usuario de la API.

El usuario de la API realiza una llamada POST a la endpoint get-auth-token(clientId,clientSecret) en el servidor de Spotnana para generar y obtener un bearer token temporal.

Aquí tienes un ejemplo de solicitud cUrl que puedes usar para llamar al 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: Reemplaza los valores de clientId y clientSecret por las credenciales que recibiste de Spotnana.

El servidor de Spotnana llama al método getToken(clientId,clientSecret) en el Spotnana IdP, que genera un bearerToken temporal y lo envía de regreso al servidor de Spotnana.
El servidor de Spotnana envía este bearer token como respuesta en formato JSON al usuario de la API.

Una vez que el usuario de la API recibe el bearer token, todas las solicitudes siguientes a las APIs de Spotnana (por ejemplo, Trip APIs) deben incluir el bearer token en el encabezado para autorización.

Nota: El endpoint get-auth-token(clientId, clientSecret) tiene un límite de 100 llamadas API cada 5 minutos.

Autenticación vía iFrame

Una solución con iFrame o incrustada es cuando los socios integran la interfaz de Spotnana dentro de su propia interfaz, lo que significa que los usuarios acceden a Spotnana desde la interfaz del socio. En este caso, la autenticación del usuario se maneja a través de un intercambio de tokens entre los sistemas del socio y Spotnana.

Nota: En la autenticación vía iFrame, al usuario que inicia sesión se le llamará caller. Esto es para contemplar escenarios donde un usuario API/máquina inicia sesión y solicita un token de acceso para otro usuario. Este usuario API/máquina puede usar credenciales de administrador TMC para conectarse directamente con el servidor de Spotnana. Por eso, utilizamos el término caller como un término general, que puede referirse tanto a un usuario que inicia sesión en su propio perfil como a un usuario API/máquina que solicita un token de acceso para otra persona.

El siguiente diagrama de secuencia muestra cómo se maneja el flujo de autenticación usando el intercambio de tokens entre Spotnana y los servidores del socio.

Fig: Diagrama de secuencia que explica la autenticación vía iFrame usando intercambio de tokens.

Paso	Flujo
Un caller inicia sesión usando la interfaz del socio.
1	La interfaz del socio muestra la interfaz de Spotnana a través de un iFrame.
2	La interfaz de Spotnana envía una solicitud a la interfaz del socio vía post message para obtener los tokens. La solicitud se envía con `type=TOKEN_EXCHANGE_REQUEST`.
3	La interfaz del socio envía una solicitud API al servidor del socio para obtener el token OAuth, iniciando los siguientes pasos en el flujo de autenticación.
3 a	El servidor del socio llama al servidor de Spotnana usando las credenciales del usuario y el token de sujeto como parámetros. El servidor de Spotnana verifica si la solicitud proviene de un usuario API/máquina.
3 b	El servidor de Spotnana llama al servidor del socio para obtener el correo electrónico del sujeto (es decir, del caller). Se obtiene el correo y se envía de regreso al servidor de Spotnana, que lo usa para identificar al usuario.
3 c	La respuesta a la solicitud API del paso 1 es enviada por el servidor de Spotnana al servidor del socio, incluyendo el token de acceso y el token de actualización. Estos datos luego se envían a la interfaz del socio.
4	La interfaz del socio envía el token a la interfaz de Spotnana vía post message con `type=TOKEN_EXCHANGE_RESPONSE.`
5	La interfaz de Spotnana envía una solicitud API al servidor de Spotnana para generar y obtener un nuevo bearer token. El servidor de Spotnana genera el bearer token y lo devuelve a la interfaz de Spotnana. Nota: La creación exitosa del bearer token indica que el usuario ya está autenticado y puede acceder a Spotnana.
6	Una vez autenticado el usuario en el paso 3, todas las siguientes solicitudes API deben incluir el bearer token, el `orgId`y el `tmcId` en el encabezado de la solicitud. El bearer token se valida en todas las solicitudes API entrantes y la respuesta se envía de regreso a la interfaz de Spotnana.

Autenticación basada en código de autorización

El siguiente diagrama de secuencia muestra cómo se maneja el flujo de autenticación usando un código de autorización.

Fig: Diagrama de secuencia que explica la autenticación basada en código de autorización.

Paso	Flujo
1	La interfaz del socio llama al servidor del socio para obtener el código de autorización del caller que va a iniciar sesión. El código se obtiene y se envía de regreso a la interfaz del socio.
2	La interfaz del socio envía una solicitud a la interfaz de Spotnana usando una URL de redirección personalizada que incluye el `tmcId` y el `authCode` como parámetros.
3	La interfaz de Spotnana hace una llamada POST a la API del servidor de Spotnana usando el endpoint `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	El servidor de Spotnana envía una solicitud al servidor del socio para obtener el `pid` del usuario usando el código de autorización. El `pid` del usuario se obtiene y se envía al servidor de Spotnana.
3 b	El servidor de Spotnana genera el token de acceso y el token de actualización, y los envía a la interfaz de Spotnana.
4	La interfaz de Spotnana envía una solicitud al servidor de Spotnana usando el token de acceso y el token de actualización para generar y obtener el bearer token de acceso. Se genera el bearer token y se envía a la interfaz de Spotnana. Nota: La creación exitosa del bearer token indica que el usuario ya está autenticado y puede acceder a Spotnana.
5	Una vez autenticado el usuario en el paso 4, todas las siguientes solicitudes API deben incluir el bearer token, el `orgId`y el `tmcId` en el encabezado de la solicitud. El bearer token se valida en todas las solicitudes API entrantes y la respuesta se envía de regreso a la interfaz de Spotnana.

Nota: Este flujo de autenticación no puede usarse en escenarios donde un administrador TMC permite que más de un usuario utilice el mismo correo electrónico para iniciar sesión.

Autenticación máquina a máquina (M2M)

El método de autenticación M2M es ideal cuando el flujo de autenticación implica que la aplicación cliente acceda a una URL de callback externa para generar el accessToken para el usuario. El siguiente diagrama de secuencia muestra cómo funciona este flujo M2M.

Fig: Diagrama de secuencia que explica el flujo de autenticación M2M.

Paso	Flujo
Las llaves públicas de todas las aplicaciones usadas en la autenticación se sincronizan entre el servidor de Spotnana y el Spotnana IdP. Más adelante, esto se usará para verificar el token de acceso durante el flujo de autenticación.
1	El servidor del socio envía una solicitud API a `/oauth2/token(clientId,clientSecret)` en el Spotnana IdP para generar un bearer token. El nuevo bearer token se envía de regreso al servidor del socio.
2	El servidor del socio envía una solicitud API a una URL de callback externa para generar un token de acceso para el usuario. Este token de acceso se crea y se envía al servidor de Spotnana.
3	El servidor de Spotnana valida la firma del token de acceso usando las llaves públicas sincronizadas previamente. También valida el `claim_id` que verifica la identidad del socio. El token de acceso se envía luego al servidor del socio para autenticar al usuario.