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

Criada por Ashish Chaudhary, Modificado em Sáb, 4 Out na (o) 11:44 AM por Ashish Chaudhary

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

ÍNDICE

Visão geral dos fluxos de autenticação da Spotnana
- Componentes principais
- Métodos de autenticação compatíveis

A Spotnana oferece diferentes formas de autenticação para que nossos parceiros possam integrar suas soluções de forma segura à nossa plataforma. Neste material, você encontra uma visão geral dos métodos de autenticação atualmente suportados pela Spotnana, além de explicações detalhadas sobre como cada fluxo funciona. Os fluxos descritos aqui mostram como a Spotnana autentica e autoriza usuários para acessar recursos protegidos da organização (ou seja, recursos da empresa do usuário dentro da plataforma Spotnana).

Componentes principais

Antes de começar, confira abaixo os principais componentes do sistema citados nesta documentação e seus significados.

Spotnana UI(Interface do Usuário da Spotnana) Refere-se ao aplicativo web da Spotnana (a ferramenta de reservas online) ou ao aplicativo móvel. Mais especificamente, é a página de login, que inicia o processo de autenticação quando o usuário acessa ou cria uma conta.
Servidor Spotnana É o servidor backend da Spotnana, responsável pela autenticação (por exemplo, autorizar o acesso do usuário a recursos e armazenar/processar dados de forma segura).
Partner UI (Interface do Usuário do Parceiro) É a interface (aplicação frontend) que os parceiros usam para acessar a plataforma Spotnana. Por exemplo, na autenticação via iFrame, a Spotnana é incorporada na interface do parceiro, e os usuários acessam a Spotnana por lá.
Servidor do parceiro Um ou mais servidores backend dos nossos parceiros, utilizados para integração com a Spotnana.
Spotnana IdP (Provedor de Identidade Spotnana) Serviço interno da Spotnana responsável pela gestão de identidade e autorização dos usuários.
Partner IdP Provedores de identidade de terceiros usados pelos parceiros, como Google ou Azure, entre outros.
OBT Ferramenta de Reservas Online (OBT) da Spotnana, disponível em https://app.spotnana.com/
Token de sujeito Na autenticação via iFrame (ou troca de tokens), o token de sujeito representa a identidade do usuário. Ele é usado para buscar informações e autorizar o acesso à plataforma Spotnana.
Token de acesso Uma credencial (OAuth) usada por aplicações parceiras para acessar recursos protegidos em nome do usuário. É uma chave temporária de autorização, permitindo que as aplicações façam requisições à API sem expor as credenciais do usuário.
Token de atualização (refresh token) Credencial de longa duração usada para obter novos tokens de acesso sem exigir que o usuário faça login novamente. Normalmente é emitido junto com o token de acesso no primeiro login.
Credenciais do cliente Informações fornecidas aos usuários que se conectam diretamente às APIs da Spotnana (ou seja, um clientId e clientSecret).
PID (Identificador pessoal) Identificador criado para o usuário. O PID serve para buscar as informações do usuário no servidor da Spotnana.
orgId Identificador único atribuído pela Spotnana para a organização do usuário.
tmcId Identificador único atribuído pela Spotnana para uma TMC (Travel Management Company).

Métodos de autenticação compatíveis

A Spotnana oferece os seguintes métodos de autenticação:

Autenticação por senha
- Usuário existente
- Novo usuário
Autenticação via IdP
Autenticação via API
Autenticação via iFrame
Autenticação por código de autorização
Autenticação máquina a máquina (M2M)

Autenticação por senha

Na autenticação por senha, a UI da Spotnana (ou seja, a página de login ou cadastro no OBT) inicia e gerencia o processo de autenticação junto aos servidores backend da Spotnana. Esse processo pode seguir dois caminhos diferentes, dependendo se o usuário está entrando com um perfil já existente ou criando um novo cadastro. Cada um desses fluxos é explicado abaixo, com diagramas de sequência para facilitar o entendimento.

Usuário existente

O diagrama de sequência e os passos abaixo mostram como a UI da Spotnana se comunica com os serviços backend para autenticar um usuário já cadastrado.

Fig: Diagrama de sequência explicando a autenticação por senha para usuários existentes.

Etapa	Fluxo
Um usuário já cadastrado faz login no OBT ou no app móvel da Spotnana usando seu e-mail.
1	A UI da Spotnana envia uma requisição de API ao servidor Spotnana para buscar as configurações de autenticação do usuário. Os dados de login do usuário vão como parâmetros nessa requisição. A resposta traz o `tmcId`, `orgId` e o tipo de `authProviderType`.
2	A UI da Spotnana faz uma chamada de API ao Spotnana IdP usando o `clientId`, e-mail e senha. O Spotnana IdP gera um novo bearer token e devolve para a UI da Spotnana. Nessa etapa, o usuário é autenticado.
3	Após a autenticação no passo 2, todas as próximas requisições de API precisam trazer o bearer token, o `orgId` e o `tmcId` no header da requisição. O bearer token é validado em todas as requisições e a resposta é enviada de volta para a UI da Spotnana.

Novo usuário

O diagrama de sequência e os passos abaixo mostram como a UI da Spotnana se comunica com os serviços backend para autenticar um novo usuário (ou um usuário existente tentando redefinir a senha).

Fig: Diagrama de sequência explicando a autenticação por senha para novos usuários.

Etapa	Fluxo
O novo usuário informa seu e-mail na página de login do OBT da Spotnana e clica em Próximo.
1	A UI da Spotnana envia uma requisição de API ao servidor Spotnana para buscar as configurações de autenticação do usuário. Os dados de login do usuário vão como parâmetros nessa requisição. A resposta traz o `tmcId`, `orgId` e o tipo de `authProviderType`.
1 a	O usuário define uma nova senha e clica em Próximo.
2	A UI da Spotnana envia uma requisição de API ao Spotnana IdP para cadastrar o usuário, informando o `clientId`, e-mail e nova senha. Depois do cadastro, uma senha de uso único (OTP) é enviada para o e-mail do usuário.
3	O usuário digita o OTP na UI da Spotnana e clica em Verificar. A UI da Spotnana envia uma solicitação ao Spotnana IdP para validar o OTP e gerar o bearer token de acesso. O bearer token é gerado e devolvido à UI da Spotnana. Isso indica que a autenticação foi feita com sucesso e o usuário pode acessar a plataforma Spotnana usando esse token.
4	Após a autenticação no passo 3, todas as próximas requisições de API precisam trazer o bearer token, o `orgId` e o `tmcId` no header da requisição. O bearer token é validado em todas as requisições e a resposta é enviada de volta para a UI da Spotnana.

Autenticação via IdP

A Spotnana permite autenticação usando IdPs como Google, Azure e IdPs personalizados via OpenID Connect, além de SAML. O diagrama de sequência e os passos abaixo mostram como funciona esse fluxo de autenticação.

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

Etapa	Fluxo
O usuário faz login pelo OBT ou pelo app móvel da Spotnana usando seu e-mail.
1	A UI da Spotnana envia uma requisição de API ao servidor Spotnana para buscar as configurações de autenticação do usuário. Os dados de login do usuário vão como parâmetros nessa requisição. A resposta traz o `tmcId`, `orgId` e o tipo de `authProviderType`.
2	A UI da Spotnana redireciona a requisição para o Spotnana IdP.
3	O Spotnana IdP redireciona a requisição para o IdP do parceiro, iniciando a autenticação via IdP para o usuário. Observação: A cada redirecionamento, o status 302 é retornado para indicar que o endereço foi redirecionado para uma nova URL.
4	É feita uma conexão entre o Spotnana IdP e o IdP do parceiro para garantir que o usuário seja autenticado pelo IdP do parceiro. Observação: Nessa conexão, o Spotnana IdP envia o `clientId` e `clientSecret` como dados codificados em URL, via chamada de API para o IdP do parceiro. Caso o servidor IdP não aceite esse formato, o servidor Spotnana pode atuar como intermediário e converter para o formato aceito pelo IdP do parceiro.
5	O IdP do parceiro autentica o usuário com sucesso. Observação: Após essa etapa, o perfil do usuário ainda precisa passar pela verificação do bearer token.
5 a	Após a autenticação, 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 usuário e envia para a UI da Spotnana.
6	A UI da Spotnana faz uma chamada de API ao Spotnana IdP usando o `clientID` e o código recebido no passo 5(b). O Spotnana IdP gera um novo bearer token e envia para a UI da Spotnana. Observação: Quando o bearer token é criado com sucesso, significa que o usuário foi autenticado e pode acessar a Spotnana.
7	Após a autenticação no passo 6, todas as próximas requisições de API precisam trazer o bearer token, o `orgId` e o `tmcId` no header da requisição. O bearer token é validado em todas as requisições e a resposta é enviada de volta para a UI da Spotnana.

Autenticação via API

Parceiros que utilizam as APIs da Spotnana para se conectar à plataforma podem usar nosso endpoint de autenticação para gerar um bearer token para seus usuários. O diagrama de sequência abaixo mostra como funciona esse fluxo de autenticação.

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

Etapa Fluxo

Etapa	Fluxo
1	O usuário da API faz uma chamada POST para o endpoint `get-auth-token(clientId,clientSecret)` no servidor Spotnana para gerar e receber um bearer token temporário. Veja um exemplo de requisição cURL para esse 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>" }' Observação: Troque os valores de `clientId` e `clientSecret` pelos dados que você recebeu da Spotnana.
2	O servidor Spotnana chama o método `getToken(clientId,clientSecret)` no Spotnana IdP, que gera um `bearerToken` e devolve ao servidor Spotnana. O servidor Spotnana envia esse bearer token como resposta em JSON para o usuário da API.

O usuário da API faz uma chamada POST para o endpoint get-auth-token(clientId,clientSecret) no servidor Spotnana para gerar e receber um bearer token temporário.

Veja um exemplo de requisição cURL para esse 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>"
}'

Observação: Troque os valores de clientId e clientSecret pelos dados que você recebeu da Spotnana.

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

Depois de receber o bearer token, todas as requisições feitas às APIs da Spotnana (por exemplo, Trip APIs) devem incluir o bearer token no cabeçalho para autorização.

Observação: O endpoint get-auth-token(clientId, clientSecret) possui um limite de 100 chamadas a cada 5 minutos.

Autenticação via iFrame

Quando parceiros incorporam a UI da Spotnana dentro da própria interface (iFrame ou solução embarcada), os usuários acessam a Spotnana pela interface do parceiro. Nesse caso, a autenticação é feita por troca de tokens entre os sistemas do parceiro e da Spotnana.

Atenção: Na autenticação via iFrame, o usuário que faz login é chamado de caller. Isso permite cenários em que um usuário de API/máquina faz login e solicita um token de acesso para outro usuário. Esse usuário de API/máquina pode, por exemplo, usar as credenciais de admin da TMC para se conectar direto ao servidor Spotnana. Por isso, usamos o termo caller como termo genérico, podendo ser tanto um usuário acessando seu próprio perfil quanto um usuário de API/máquina solicitando acesso para outro.

O diagrama de sequência abaixo mostra como funciona o fluxo de autenticação via troca de tokens entre Spotnana e os servidores do parceiro.

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

Etapa	Fluxo
O caller faz login usando a interface do parceiro.
1	A interface do parceiro carrega a UI da Spotnana via iFrame.
2	A UI da Spotnana envia uma mensagem para a UI do parceiro (post message) solicitando os tokens, com o parâmetro `type=TOKEN_EXCHANGE_REQUEST`.
3	A UI do parceiro faz uma chamada de API ao servidor do parceiro para buscar o token OAuth, iniciando os próximos passos do fluxo de autenticação.
3 a	O servidor do parceiro chama o servidor Spotnana usando as credenciais do usuário e o token de sujeito como parâmetros. O servidor Spotnana verifica se a requisição veio de um usuário de API/máquina.
3 b	O servidor Spotnana chama o servidor do parceiro para obter o e-mail do sujeito (ou seja, do caller). O e-mail é recuperado e devolvido ao servidor Spotnana, que usa essa informação para identificar o usuário.
3 c	A resposta da requisição do passo 1 é enviada pelo servidor Spotnana ao servidor do parceiro, contendo o access token e o refresh token. Esses dados são então enviados para a UI do parceiro.
4	A UI do parceiro envia o token para a UI da Spotnana via post message com `type=TOKEN_EXCHANGE_RESPONSE.`
5	A UI da Spotnana faz uma chamada de API ao servidor Spotnana para gerar e receber um novo bearer token. O servidor Spotnana gera o bearer token e devolve para a UI da Spotnana. Observação: Quando o bearer token é criado com sucesso, significa que o usuário foi autenticado e pode acessar a Spotnana.
6	Após a autenticação no passo 3, todas as próximas requisições de API precisam trazer o bearer token, o `orgId` e o `tmcId` no header da requisição. O bearer token é validado em todas as requisições e a resposta é enviada de volta para a UI da Spotnana.

Autenticação por código de autorização

O diagrama de sequência abaixo mostra como funciona o fluxo de autenticação usando um código de autorização.

Fig: Diagrama de sequência explicando a autenticação por código de autorização.

Etapa	Fluxo
1	A UI do parceiro chama o servidor do parceiro para obter o auth code do caller que está fazendo login. O auth code é recuperado e enviado de volta para a UI do parceiro.
2	A UI do parceiro envia uma requisição para a UI da Spotnana usando uma URL de redirecionamento personalizada, incluindo o `tmcId` e `authCode` como parâmetros.
3	A UI da Spotnana faz uma chamada POST para a API do servidor Spotnana usando o endpoint `v2/auth/token/companies/<tmcId>(authCode)` .
3 a	O servidor Spotnana faz uma solicitação ao servidor do parceiro para obter o `pid` do usuário, usando o auth code. O `pid` do usuário é recuperado e enviado ao servidor Spotnana.
3 b	O servidor Spotnana gera o access token e o refresh token e envia para a UI da Spotnana.
4	A UI da Spotnana faz uma requisição ao servidor Spotnana usando o access token e o refresh token para gerar e receber o bearer token de acesso. O bearer token é gerado e enviado para a UI da Spotnana. Observação: Quando o bearer token é criado com sucesso, significa que o usuário foi autenticado e pode acessar a Spotnana.
5	Após a autenticação no passo 4, todas as próximas requisições de API precisam trazer o bearer token, o `orgId` e o `tmcId` no header da requisição. O bearer token é validado em todas as requisições e a resposta é enviada de volta para a UI da Spotnana.

Observação: Esse fluxo de autenticação não pode ser usado em situações onde o admin da TMC permite que mais de um usuário utilize o mesmo e-mail para login.

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

O método M2M é ideal quando o fluxo de autenticação envolve o aplicativo do cliente acessando uma URL de callback de terceiros para gerar o accessToken para o usuário. O diagrama de sequência abaixo mostra como funciona o fluxo M2M.

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

Etapa	Fluxo
As chaves públicas de todos os aplicativos usados na autenticação são sincronizadas entre o servidor Spotnana e o Spotnana IdP. Elas serão usadas depois para validar o token de acesso durante o fluxo.
1	O servidor do parceiro faz uma chamada de 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 faz uma chamada de API para uma URL de callback de terceiros para gerar um access token para o usuário. Esse access token é criado e enviado ao 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` para garantir a identidade do parceiro. O access token é então enviado ao servidor do parceiro para autenticar o usuário.