Visão geral dos métodos de autenticação da Spotnana

Criada por Ashish Chaudhary, Modificado em Sun, 5 Out às 7:07 PM por Ashish Chaudhary

Visão geral dos fluxos de autenticação Spotnana

ÍNDICE

Visão geral dos fluxos de autenticação Spotnana
- Componentes principais
- Métodos de autenticação suportados

A Spotnana disponibiliza vários métodos de autenticação para que os parceiros possam integrar-se de forma segura com a nossa plataforma. Nesta documentação encontra uma visão geral dos métodos de autenticação atualmente suportados pela Spotnana, bem como explicações detalhadas sobre o funcionamento de cada um. Os diferentes fluxos de autenticação aqui descritos mostram como a Spotnana valida e autoriza utilizadores para acederem a recursos protegidos ao nível da organização (ou seja, recursos pertencentes à empresa do utilizador na plataforma Spotnana).

Componentes principais

Antes de começar, consulte esta lista para conhecer os principais componentes do sistema referidos nesta documentação.

Spotnana UI(Interface de Utilizador da Spotnana) Refere-se à aplicação web da Spotnana (ou seja, a ferramenta de reservas online) ou à aplicação móvel da Spotnana. Mais concretamente, diz respeito à página de login, que inicia o fluxo de autenticação sempre que o utilizador faz login ou cria uma nova conta.
Servidor Spotnana Refere-se ao servidor backend da Spotnana, responsável pela autenticação (por exemplo, autorizar o acesso a recursos e guardar/processar informações dos utilizadores de forma segura).
UI do parceiro (Interface de Utilizador do Parceiro) Interface utilizada pelos parceiros para aceder à plataforma Spotnana (ou seja, a aplicação frontend). Por exemplo, na autenticação via iFrame, a plataforma Spotnana é incorporada na interface do parceiro e os utilizadores acedem à Spotnana através dessa interface.
Servidor do parceiro Refere-se a um ou mais servidores backend utilizados pelos nossos parceiros para integrarem com a Spotnana.
Spotnana IdP (Fornecedor de Identidade Spotnana) Serviço interno da Spotnana utilizado para gestão de identidades e autorização de utilizadores.
IdP do parceiro Fornecedores de identidade externos (IdP) usados pelos parceiros. Exemplos comuns são o Google e o Azure.
OBT Ferramenta de Reservas Online (OBT) da Spotnana, disponível em https://app.spotnana.com/
Token de utilizador (subject token) Na autenticação via iFrame (ou por troca de tokens), o subject token representa a identidade do utilizador. Este token serve para identificar o utilizador e autorizar o acesso à plataforma Spotnana.
Token de acesso (access token) Credencial (OAuth) usada por uma aplicação parceira para aceder a recursos protegidos em nome de um utilizador. É uma chave de autorização temporária, que permite fazer pedidos à API sem expor as credenciais do utilizador.
Token de renovação (refresh token) Credencial de longa duração que permite obter novos tokens de acesso sem que o utilizador tenha de voltar a autenticar-se. Normalmente é emitida juntamente com o token de acesso na primeira sessão de login.
Credenciais de cliente (client credentials) Informação fornecida aos utilizadores que se ligam diretamente às APIs da Spotnana (ou seja, um identificador clientId e clientSecret).
PID (Identificador pessoal) Identificador pessoal criado para o utilizador. O PID permite obter a informação do utilizador a partir do servidor Spotnana.
orgId Identificador único atribuído pela Spotnana à organização do utilizador.
tmcId Identificador único atribuído pela Spotnana a uma TMC (Travel Management Company).

Métodos de autenticação suportados

Estes são os vários métodos de autenticação suportados pela Spotnana:

Autenticação por palavra-passe
- Utilizador já existente
- Novo utilizador
Autenticação via IdP
Autenticação via API
Autenticação via iFrame
Autenticação baseada em código de autorização
Autenticação máquina-a-máquina (M2M)

Autenticação por palavra-passe

Quando se utiliza a autenticação por palavra-passe, a Spotnana UI (ou seja, a página de login ou registo no OBT) inicia e gere o processo de autenticação com os servidores backend da Spotnana. Este método pode seguir dois fluxos diferentes, consoante o utilizador esteja a entrar com um perfil já existente ou esteja a criar uma conta nova. Ambos os fluxos são explicados nas secções seguintes, com diagramas de sequência.

Utilizador já existente

O diagrama de sequência e os passos abaixo mostram como a Spotnana UI comunica com os serviços backend para autenticar um utilizador já existente.

Fig: Diagrama de sequência que explica a autenticação por palavra-passe para utilizadores já existentes.

Passo	Fluxo
Um utilizador já existente faz login no OBT ou na aplicação móvel da Spotnana, usando o seu email.
1	A Spotnana UI envia um pedido API ao servidor Spotnana para obter as configurações de autenticação desse utilizador. O pedido inclui as credenciais de login do utilizador como parâmetros. A resposta inclui o `tmcId`, o `orgId`e o `authProviderType`do utilizador.
2	A Spotnana UI envia um pedido API ao Spotnana IdP com o `clientId`, email e palavra-passe. O Spotnana IdP gera e devolve um novo bearer token à Spotnana UI. Neste passo, o utilizador fica autenticado.
3	Depois de autenticado no passo 2, todos os pedidos API seguintes devem incluir o bearer token, o `orgId`e o `tmcId` no cabeçalho do pedido. O bearer token é validado em todos os pedidos API recebidos e a resposta é devolvida à Spotnana UI.

Novo utilizador

O diagrama de sequência e os passos abaixo mostram como a Spotnana UI comunica com os serviços backend para autenticar um novo utilizador (ou um utilizador já existente que esteja a repor a palavra-passe).

Fig: Diagrama de sequência que explica a autenticação por palavra-passe para novos utilizadores.

Passo	Fluxo
Um novo utilizador introduz o seu email na página de login do OBT da Spotnana e clica em Seguinte.
1	A Spotnana UI envia um pedido API ao servidor Spotnana para obter as configurações de autenticação do utilizador. O pedido inclui as credenciais de login como parâmetros. A resposta inclui o `tmcId`, o `orgId`e o `authProviderType`do utilizador.
1 a	O utilizador define uma nova palavra-passe e clica em Seguinte.
2	A Spotnana UI envia um pedido API ao Spotnana IdP para registar o utilizador, juntamente com o `clientId`, email e a nova palavra-passe. Após o registo dos dados, é enviado um código de validação (OTP) para o email do utilizador.
3	O utilizador insere o OTP na Spotnana UI e clica em Verificar. A Spotnana UI envia um pedido ao Spotnana IdP para validar o OTP e gerar um bearer token para login. O bearer token é gerado e devolvido à Spotnana UI. Isto significa que o utilizador ficou autenticado com sucesso e pode aceder à plataforma Spotnana com o bearer token.
4	Depois do utilizador estar autenticado no passo 3, todos os pedidos API seguintes devem incluir o bearer token, o `orgId`e o `tmcId` no cabeçalho do pedido. O bearer token é validado em todos os pedidos API recebidos e a resposta é devolvida à Spotnana UI.

Autenticação via IdP

A Spotnana permite autenticação através de IdPs como Google, Azure e IdPs personalizados usando OpenID Connect, bem como protocolos SAML. O diagrama de sequência e os passos seguintes explicam o fluxo de autenticação via IdP.

Fig: Diagrama de sequência que explica o fluxo de autenticação via IdP.

Passo	Fluxo
Um utilizador faz login no OBT ou na aplicação móvel da Spotnana, usando o seu email.
1	A Spotnana UI envia um pedido API ao servidor Spotnana para obter as configurações de autenticação do utilizador. O pedido inclui as credenciais de login como parâmetros. A resposta inclui o `tmcId`, o `orgId`e o `authProviderType`do utilizador.
2	A Spotnana UI redireciona o pedido para o Spotnana IdP.
3	O Spotnana IdP redireciona o pedido para o IdP do parceiro, iniciando a autenticação do utilizador nesse IdP. Nota: Em cada redirecionamento, é devolvido o código de estado 302 para indicar que o pedido foi encaminhado para outro URL.
4	É estabelecida uma ligação entre o Spotnana IdP e o IdP do parceiro, para garantir que o utilizador é autenticado pelo IdP do parceiro. Nota: Nesta ligação, o Spotnana IdP envia o `clientId` e o `clientSecret` como dados codificados em URL através de um pedido API ao IdP do parceiro. Se os servidores IdP não conseguirem processar este formato, o servidor Spotnana pode atuar como intermediário e converter os dados para um formato aceite pelo IdP do parceiro.
5	O IdP do parceiro autentica o utilizador com sucesso. Nota: Após este passo, o perfil do utilizador ainda tem de passar pela verificação do bearer token.
5 a	Depois da autenticação bem-sucedida, a resposta do IdP do parceiro é enviada para o Spotnana IdP.
5 b	O Spotnana IdP gera um código único para o perfil do utilizador e envia-o para a Spotnana UI.
6	A Spotnana UI envia um pedido API ao Spotnana IdP com o `clientID` e o código recebido no passo 5(b). O Spotnana IdP gera um novo bearer token e envia-o à Spotnana UI. Nota: A criação bem-sucedida do bearer token indica que o utilizador está autenticado e pode aceder à Spotnana.
7	Depois do utilizador estar autenticado no passo 6, todos os pedidos API seguintes devem incluir o bearer token, o `orgId`e o `tmcId` no cabeçalho do pedido. O bearer token é validado em todos os pedidos API recebidos e a resposta é devolvida à Spotnana UI.

Autenticação via API

Os parceiros que utilizam as APIs da Spotnana para se ligarem à plataforma podem usar o nosso endpoint de autenticação para gerar um bearer token para os seus utilizadores. O diagrama de sequência seguinte ilustra o fluxo de autenticação para qualquer parceiro que utilize a autenticação via API.

Fig: Diagrama de sequência que explica a autenticação via API.

Passo Fluxo

Passo	Fluxo
1	O utilizador da API faz um pedido POST ao endpoint `get-auth-token(clientId,clientSecret)` na API do servidor Spotnana para gerar e obter um bearer token temporário. Eis um exemplo de pedido cUrl para utilizar ao chamar o 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: Substitua os valores de `clientId` e `clientSecret` pelas credenciais que recebeu da Spotnana.
2	O servidor Spotnana chama o método `getToken(clientId,clientSecret)` no Spotnana IdP, que gera um `bearerToken` temporário e o devolve ao servidor Spotnana. O servidor Spotnana envia este bearer token como resposta JSON ao utilizador da API.

O utilizador da API faz um pedido POST ao endpoint get-auth-token(clientId,clientSecret) na API do servidor Spotnana para gerar e obter um bearer token temporário.

Eis um exemplo de pedido cUrl para utilizar ao chamar o 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: Substitua os valores de clientId e clientSecret pelas credenciais que recebeu da Spotnana.

O servidor Spotnana chama o método getToken(clientId,clientSecret) no Spotnana IdP, que gera um bearerToken temporário e o devolve ao servidor Spotnana.
O servidor Spotnana envia este bearer token como resposta JSON ao utilizador da API.

Depois de receber o bearer token, todos os pedidos seguintes feitos às APIs da Spotnana (por exemplo, APIs de Viagens) devem incluir o bearer token no cabeçalho para autorização.

Nota: O endpoint get-auth-token(clientId, clientSecret) tem um limite de 100 chamadas API por cada 5 minutos.

Autenticação via iFrame

Uma solução iFrame ou embutida é quando os parceiros integram a Spotnana UI na sua própria interface, ou seja, os utilizadores acedem à Spotnana através da interface do parceiro. Neste cenário, a autenticação do utilizador é feita com base na troca de tokens entre os sistemas do parceiro e da Spotnana.

Nota: Na autenticação via iFrame, o utilizador que faz login será referido como caller. Isto permite abranger cenários em que um utilizador API/máquina faz login e pede um token de acesso para outro utilizador. Este utilizador API/máquina pode, por exemplo, usar credenciais de administrador da TMC para se ligar diretamente ao servidor Spotnana. Por isso, utilizamos o termo caller como termo genérico, podendo referir-se tanto a um utilizador que entra no seu próprio perfil, como a um utilizador API/máquina que pede um token de acesso para outro utilizador.

O diagrama de sequência seguinte ilustra como o fluxo de autenticação é gerido através da troca de tokens entre a Spotnana e os servidores do parceiro.

Fig: Diagrama de sequência que explica a autenticação via iFrame usando troca de tokens.

Passo	Fluxo
Um caller faz login através da UI do parceiro.
1	A UI do parceiro apresenta a Spotnana UI através de um iFrame.
2	A Spotnana UI envia um pedido à UI do parceiro via post message para obter os tokens. O pedido é enviado com `type=TOKEN_EXCHANGE_REQUEST`.
3	A UI do parceiro envia um pedido API ao servidor do parceiro para obter o token OAuth, iniciando os passos seguintes do fluxo de autenticação.
3 a	O servidor do parceiro chama o servidor Spotnana usando as credenciais do utilizador e o subject token como parâmetros. O servidor Spotnana verifica se o pedido foi feito por um utilizador API/máquina.
3 b	O servidor Spotnana chama o servidor do parceiro para obter o email do subject (ou seja, do caller). O email é obtido e devolvido ao servidor Spotnana, que o utiliza para identificar o utilizador.
3 c	A resposta ao pedido API do passo 1 é enviada pelo servidor Spotnana ao servidor do parceiro, incluindo o access token e o refresh token. Estes dados são depois enviados para a UI do parceiro.
4	A UI do parceiro envia o token à Spotnana UI via post message com `type=TOKEN_EXCHANGE_RESPONSE.`
5	A Spotnana UI envia um pedido API ao servidor Spotnana para gerar e obter um novo bearer token. O bearer token é gerado pelo servidor Spotnana e devolvido à Spotnana UI. Nota: A criação bem-sucedida do bearer token indica que o utilizador está autenticado e pode aceder à Spotnana.
6	Depois do utilizador estar autenticado no passo 3, todos os pedidos API seguintes devem incluir o bearer token, o `orgId`e o `tmcId` no cabeçalho do pedido. O bearer token é validado em todos os pedidos API recebidos e a resposta é devolvida à Spotnana UI.

Autenticação baseada em código de autorização

O diagrama de sequência seguinte mostra como o fluxo de autenticação é gerido através de um código de autorização.

Fig: Diagrama de sequência que explica a autenticação baseada em código de autorização.

Passo	Fluxo
1	A UI do parceiro chama o servidor do parceiro para obter o auth code do caller que está a fazer login. O auth code é obtido e devolvido à UI do parceiro.
2	A UI do parceiro envia um pedido à Spotnana UI usando um URL de redirecionamento personalizado, incluindo o `tmcId` e o `authCode` como parâmetros.
3	A Spotnana UI faz um pedido POST à API do servidor Spotnana, usando o endpoint `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	O servidor Spotnana envia um pedido ao servidor do parceiro para obter o `pid` do utilizador, usando o auth code. O `pid` do utilizador é obtido e enviado para o servidor Spotnana.
3 b	O access token e o refresh token são gerados pelo servidor Spotnana e enviados para a Spotnana UI.
4	A Spotnana UI envia um pedido ao servidor Spotnana, usando o access token e o refresh token, para gerar e obter um bearer token de acesso. O bearer token é gerado e enviado para a Spotnana UI. Nota: A criação bem-sucedida do bearer token indica que o utilizador está autenticado e pode aceder à Spotnana.
5	Depois do utilizador estar autenticado no passo 4, todos os pedidos API seguintes devem incluir o bearer token, o `orgId`e o `tmcId` no cabeçalho do pedido. O bearer token é validado em todos os pedidos API recebidos e a resposta é devolvida à Spotnana UI.

Nota: Este fluxo de autenticação não pode ser utilizado em situações em que um administrador da TMC permite que mais do que um utilizador faça login com o mesmo email.

Autenticação máquina-a-máquina (M2M)

O método de autenticação M2M é indicado quando o fluxo de autenticação envolve a aplicação cliente aceder a um URL de callback externo para gerar o accessToken para o utilizador. O diagrama de sequência seguinte ilustra o fluxo de autenticação M2M.

Fig: Diagrama de sequência que explica o fluxo de autenticação M2M.

Passo	Fluxo
As chaves públicas de todas as aplicações envolvidas na autenticação são sincronizadas entre o servidor Spotnana e o Spotnana IdP. Estas chaves serão usadas mais tarde para validar o access token no fluxo de autenticação.
1	O servidor do parceiro envia um pedido API para `/oauth2/token(clientId,clientSecret)` no Spotnana IdP para gerar um bearer token. O novo bearer token é devolvido ao servidor do parceiro.
2	O servidor do parceiro envia um pedido API a um URL de callback externo para gerar um access token para o utilizador. O access token é criado e enviado para o servidor Spotnana.
3	O servidor Spotnana valida a assinatura do access token usando as chaves públicas sincronizadas anteriormente. Também valida o `claim_id` que confirma a identidade do parceiro. O access token é então enviado ao servidor do parceiro para autenticar o utilizador.