Spotnana authentication flows - Overview

Modified on Thu, 21 Nov at 4:10 PM

Spotnana authentication flows - Overview

TABLE OF CONTENTS

Spotnana authentication flows - Overview
- Key components
- Supported authentication methods

Spotnana offers various authentication methods that allow partners to support secure integration with our platform. This documentation provides an overview of the different authentication methods currently supported by Spotnana, along with detailed explanations of their process flow. The different authentication flows mentioned here demonstrate how Spotnana authenticates and authorizes users to access protected organization-level resources (i.e., the resources owned by the user’s company on the Spotnana platform).

Key components

Before you get started, review this list for definitions of the essential system components referred to in this documentation.

Spotnana UI(Spotnana User Interface) Refers to the Spotnana frontend web application (i.e., the Online Booking Tool) or the Spotnana mobile application. More specifically, it refers to the login page, which triggers the frontend authentication flow when the user logs in or creates a new login.
Spotnana server Refers to the Spotnana backend server used for authentication purposes (e.g., authorizing a user to access a resource and to store and process user information safely).
Partner UI (Partner's User Interface) The user interface (i.e., the frontend application) used by the partners to access the Spotnana platform. For example, in the iFrame-based authentication, the Spotnana platform is embedded into the partner’s User Interface (UI) and their users will access Spotnana via the partner UI.
Partner server Refers to one or more backend servers used by our partners to integrate with Spotnana.
Spotnana IdP (Spotnana Identity Provider) Refers to Spotnana’s internal service used for user identity management and authorization.
Partner IdP Third-party Identity Providers (IdP) used by the partners. Some common IdPs are Google and Azure.
OBT Spotnana’s Online Booking Tool (OBT), which can be accessed at https://app.spotnana.com/
Subject token In iFrame-based (or token exchange) authentication, a subject token represents the user's identity. This token will be used to look up their information and authorize them to access the Spotnana platform.
Access token A credential (OAuth) used by a partner application to access protected resources on behalf of a user. It is a temporary authorization key, allowing applications to make API requests without exposing the user's credentials.
Refresh token A long-lived credential used to obtain new access tokens without requiring the user to re-authenticate. This is usually issued along with the access token when it’s created during the first login session.
Client credentials The information provided to the users who are directly connecting to Spotnana APIs (i.e., a unique clientId and clientSecret).
PID (Personal identifier) A personal identifier created for the user. The PID retrieves the user information from the Spotnana server.
orgId A unique identifier assigned by Spotnana for the user’s organization.
tmcId A unique identifier assigned by Spotnana for a TMC (Travel Management Company).

Supported authentication methods

The following are the various authentication methods supported by Spotnana:

Password-based authentication
- Existing user
- New user
IDP-based authentication
API-based authentication
iFrame-based authentication
Auth code-based authentication
Machine-to-machine (M2M) authentication

Password-based authentication

When using password-based authentication, the Spotnana UI (i.e., the login or signup page in the OBT) initiates and manages the authentication process with the Spotnana backend servers. This approach can have two different flows depending on whether the user logs in with an existing profile or signs up to create a new profile. Each of these two authentication flows are explained in the sections below using sequence diagrams.

Existing user

The sequence diagram and the steps below explain how the Spotnana UI interacts with the backend services to authenticate an existing user.

Fig: A sequence diagram explaining the password-based authentication for existing users.

Step	Flow
An existing user logs in via the OBT or the Spotnana mobile application using their email.
1	The Spotnana UI sends an API request to the Spotnana server to retrieve the auth configuration information for the user. The request contains the user's login credentials as parameters. The response contains the user’s `tmcId`, `orgId`, and `authProviderType`.
2	The Spotnana UI sends an API request to the Spotnana IdP using the `clientId`, email, and password. A new bearer token is generated by the Spotnana IdP and returned to the Spotnana UI. This step authenticates the user.
3	Once the user is authenticated in step 2, all further API requests must contain the bearer token, the `orgId`, and the `tmcId` in the request header. The bearer token is validated in all the incoming API requests and the response is sent back to the Spotnana UI.

New user

The sequence diagram and the steps below explain how the Spotnana UI interacts with the backend services to authenticate a new user (or an existing user who’s trying to reset their password).

Fig: A sequence diagram explaining the password-based authentication for new users.

Step	Flow
A new or an existing user enters their email on the Spotnana OBT login page and clicks Next.
1	The Spotnana UI sends an API request to the Spotnana server to retrieve the auth configuration information for the user. The request contains the user's login credentials as parameters. The response contains the user’s `tmcId`, `orgId`, and `authProviderType`.
1 a	The user enters a new password and clicks Next.
2	The Spotnana UI sends an API request to the Spotnana IdP to register the user along with their `clientId`, email, and new password. After the details are registered, a One-Time Password (OTP) is sent to the user’s email.
3	The user enters the OTP in the Spotnana UI and clicks Verify. The Spotnana UI sends a request to the Spotnana IdP to verify the OTP and generate a bearer token for login. The bearer token is generated and returned to Spotnana UI. This indicates a successful authentication of the user to access the Spotnana platform using the bearer token.
4	Once the user is authenticated in step 3, all further API requests must contain the bearer token, the `orgId`, and the `tmcId` in the request header. The bearer token is validated in all the incoming API requests and the response is sent back to the Spotnana UI.

IDP-based authentication

Spotnana supports authentication via IDPs such as Google, Azure, and custom IDPs using OpenID connect, as well as SAML protocols. The sequence diagram and the steps below explain the IDP-based authentication flow.

Fig: A sequence diagram explaining the IDP-based authentication flow.

Step	Flow
A user logs in via the OBT or the Spotnana mobile application using their email.
1	The Spotnana UI sends an API request to the Spotnana server to retrieve the auth configuration information for the user. The request contains the user's login credentials as parameters. The response contains the user’s `tmcId`, `orgId`, and `authProviderType`.
2	Spotnana UI redirects the request to the Spotnana IdP.
3	The Spotnana IdP redirects the request to the partner’s IdP. This initiates the IdP authentication for the user. Note: For every redirect, a 302 status code is returned to indicate that the request has been redirected to a different URL.
4	A connection is established between the Spotnana IdP and the partner IdP. This connection is established to ensure the user is authenticated by the partner IdP. Note: During this connection, Spotnana IdP sends the `clientId` and `clientSecret` as a form URL-encoded data using an API call to the Partner IdP. If the IdP servers are unable to process this data format, the Spotnana server can act as a proxy to translate the data into a format recognized by the partner IdP.
5	The partner IdP successfully authenticates the user. Note: After this step, the user profile must still go through the bearer token verification.
5 a	After successful authentication, the response from the partner IdP is sent to the Spotnana IdP.
5 b	The Spotnana IdP generates a unique code for the user profile and sends it to Spotnana UI.
6	Spotnana UI sends an API request to Spotnana IdP using the `clientID` and the code received in step 5(b). Spotnana IdP generates a new bearer token and sends it to Spotnana UI. Note: A successful creation of bearer token indicates that the user has been authenticated and is allowed to access Spotnana.
7	Once the user is authenticated in step 6, all further API requests must contain the bearer token, the `orgId`, and the `tmcId` in the request header. The bearer token is validated in all the incoming API requests and the response is sent back to the Spotnana UI.

API-based authentication

Partners who use Spotnana’s APIs to connect to the Spotnana platform can use our authentication endpoint to generate a bearer token for their users. The following sequence diagram illustrates the authentication flow for any partner using API-based authentication.

Fig: A sequence diagram explaining the API-based authentication.

Step Flow

Step	Flow
1	The API user makes a POST call to the `get-auth-token(clientId,clientSecret)` API endpoint in the Spotnana server to generate and retrieve a temporary bearer token. Heres a sample cUrl request to use when calling the `get-auth-token` endpoint: curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' Note: Replace the `clientId` and `clientSecret` values with the credentials you have received from Spotnana.
2	The Spotnana server calls the `getToken(clientId,clientSecret)` method in the Spotnana IdP, which generates a temporary `bearerToken` and sends it back to the Spotnana server. The Spotnana server sends this bearer token as a JSON response to the API user.

The API user makes a POST call to the get-auth-token(clientId,clientSecret) API endpoint in the Spotnana server to generate and retrieve a temporary bearer token.

Heres a sample cUrl request to use when calling the get-auth-token endpoint:

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

Note: Replace the clientId and clientSecret values with the credentials you have received from Spotnana.

The Spotnana server calls the getToken(clientId,clientSecret) method in the Spotnana IdP, which generates a temporary bearerToken and sends it back to the Spotnana server.
The Spotnana server sends this bearer token as a JSON response to the API user.

Once the API user has received the bearer token, all the subsequent requests made to Spotnana APIs (e.g., Trip APIs) must include the bearer token in the header for authorization.

Note: The get-auth-token(clientId, clientSecret) endpoint has a rate limit of 100 API calls per 5 minutes.

iFrame-based authentication

An iFrame or an embedded solution is when partners embed the Spotnana UI into the partner UI, which means users access Spotnana via the partner UI. In this scenario, the user authentication is handled based on token exchange between the partner and Spotnana systems.

Note: For iFrame-based authentication, the user logging in will be referred to as a caller. This is to allow for specific scenarios where an API/Machine user logs in and requests an access token for another user. This API/Machine user could use TMC (Travel Management Company) admin credentials to connect directly with the Spotnana server. Hence, we’ll be using caller as a generalized term, which can refer to a user logging into their own profile or an API/Machine user requesting an access token for another user.

The following sequence diagram illustrates how the authentication flow is handled using a token exchange between Spotnana and the partner servers.

Fig: A sequence diagram explaining the iFrame-based authentication using token exchange.

Step	Flow
A caller logs in using the Partner UI.
1	The Partner UI sends an API request to the partner server to retrieve the OAuth token, initiating the next consecutive steps in the authentication flow.
1 a	The partner server calls the Spotnana server using the user credentials and the subject token as parameters. The Spotnana server checks if the incoming request is sent by an API/Machine user.
1 b	The Spotnana server calls the partner server to retrieve the subject (i.e., the caller) email. The email is fetched and returned to the Spotnana server, which is used to identify the user.
1 c	The response to the API request from step 1 is sent by the Spotnana server to the partner server containing the access token and the refresh token. These details are then sent to the Partner UI.
2	The Partner UI sends a request to the Spotnana UI using a custom redirect URL. The request contains the access token and refresh token as parameters.
3	The Spotnana UI sends an API request to the Spotnana server to generate and retrieve a new bearer token. A bearer token is generated by the Spotnana server and returned to the Spotnana UI. Note: A successful creation of bearer token indicates that the user has been authenticated and is allowed to access Spotnana.
4	Once the user is authenticated in step 3, all further API requests must contain the bearer token, the `orgId`, and the `tmcId` in the request header. The bearer token is validated in all the incoming API requests and the response is sent back to the Spotnana UI.

Auth code-based authentication

The following sequence diagram illustrates how the authentication flow is handled using an authorization code.

Fig: A sequence diagram explaining the auth code-based authentication using auth code.

Step	Flow
1	The partner UI calls the partner server to retrieve the auth code for the caller logging in. The auth code is retrieved and sent back to the partner UI.
2	The Partner UI sends a request to the Spotnana UI using a custom redirect URL containing the `tmcId` and `authCode` as parameters.
3	Spotnana UI makes a POST API call to Spotnana server using the `v2/auth/token/companies/<tmcId>(authCode)` API endpoint.
3 a	Spotnana server sends a request to partner server to retrieve the user’s `pid` using the auth code. The user’s `pid` is retrieved and sent to the Spotnana server.
3 b	The access token and refresh token are generated by the Spotnana server and sent to Spotnana UI.
4	Spotnana UI sends a request to the Spotnana server using the access token and refresh token to generate and retrieve a bearer token for access. A bearer token is generated and sent to Spotnana UI. Note: A successful creation of bearer token indicates that the user has been authenticated and is allowed to access Spotnana.
5	Once the user is authenticated in step 4, all further API requests must contain the bearer token, the `orgId`, and the `tmcId` in the request header. The bearer token is validated in all the incoming API requests and the response is sent back to the Spotnana UI.

Note: This authentication flow cannot be used in scenarios where a TMC admin allows more than one user to use the same email when logging in.

Machine-to-machine (M2M) authentication

The M2M authentication method is suitable when the authentication flow involves the client application accessing a third-party callback URL to generate the accessToken for the user. The following sequence diagram illustrates the M2M authentication flow.

Fig: A sequence diagram explaining the M2M authentication flow.

Step	Flow
The public keys for all the applications used in the authentication are synced between Spotnana server and Spotnana IdP. This will later be used to verify the access token in the authentication flow.
1	The partner server sends an API request to `/oauth2/token(clientId,clientSecret)` in Spotnana IdP to generate a bearer token. The new bearer token is sent back to the partner server.
2	The partner server sends an API request to a third-party callback URL to generate an access token for the user. This access token is created and sent to the Spotnana server.
3	The Spotnana server validates the access token signature using the public keys synced earlier. It also validates the `claim_id` which verifies the partner’s identity. The access token is then sent to the partner server to authenticate the user.