OAuth2 | Sessão de usuário

01. DADOS GERAIS

02. SITUAÇÃO/REQUISITO

Para atendimento da demanda de autenticação, para o produto TOTVS Recintos Aduaneiros, através do protocolo OAuth2 foram estabelecidas a condições para o estabelecimento da sessão de usuário junto ao ecossistema Recintos Aduaneiros.

03. SOLUÇÃO

Para atendimento aos requisitos necessários para efetivação da sessão, as solicitações envidadas ao endpoint devem conter as informações listadas a seguir:

1. 1. Informação do identificador CLIENT ID;
   2. Informação do identificador CLIENT SECRET;
   3. Código de login do usuário (c+CPF) e;
   4. Senha pessoal do usuário.

Os dados solicitados pelo endpoint devem ser enviados seguindo os modos Client Credentials e Password Grant do protocolo OAuth2 e serão recepcionados pela API para a efetivação da ação de login. Uma vez validados os parâmetros, a API responderá com um token válido para a sessão, onde seus aspectos principais estarão definidos. Permissões e demais critérios de sessão estarão disponíveis através do token Bearer fornecido, e sua validade padrão será 20 (vinte) minutos. Uma vez expirado, o token perderá sua validade, o que impossibilitará a troca de mensagens entre as APIs TOTVS Recintos Aduaneiros e seus clientes.

Para a renovação da sessão, o cliente deverá acessar o endpoint de autenticação, fornecendo o refresh token obtido no início da sessão. É importante lembrar que, para este fim, o refresh token só pode ser utilizado uma única vez de forma a garantir o correto estabelecimento de sessões de usuário. O uso de um refresh token em um processo de renovação de sessão gerará um novo par de tokens - sessão e renovação -, os quais são validados em conjunto para a ação de renovação. O token de renovação tem um tempo de vida de cinco minutos, contatos a partir da expiração do token de sessão e não pode ser utilizado antes da expiração ocorrer.

Para o estabelecimento de sessões, onde o servidor OAuth2 esteja implementado - utilizando-se, por exemplo, o protocolo HTTP para rede local ou HTTPS para implantação em ambientes externos, e tendo os endereços http://[servidor] ou https://[servidor] como a diretiva [servidor] -, deve-se seguir as seguintes instruções:

1. 1. Utilizar o endpoint [servidor]/api/sara/authentication/v1/session/token para obter um token JWT válido para transações com os serviços do ecossistema Recintos Aduaneiros com o parâmetro grant_type setado em:
      1. client_credentials: para obtenção do token através dos parâmetros client_id e client_secret ou;
      2. password: para obtenção do token através dos parâmetros username e password, cumulados ou não com os parâmetros client_id e client_secret;
   2. Utilizar o endpoint [servidor]/api/sara/authentication/v1/session/token para restaurar uma sessão de usuário utilizando o respectivo refresh token com o parâmetro grant_type setado em refresh_token para obtenção do token através do parâmetro refresh_token.

Não haverá disponibilidade de sessões simultâneas para um mesmo usuários dentro de um mesmo escopo - sendo os escopos disponíveis desktop, mobile e web. Sendo assim, o início de uma nova sessão dentro de um escopo em que o usuário possua uma sessão aberta, anulará a sessão anterior. Isso impedirá o usuário de ter múltiplas sessões simultâneas que não estejam em escopos diferentes - uma sessão desktop e outra mobile, por exemplo -, permitindo um controle mais preciso do uso de licenças junto à TOTVS.

Além disso, quando detectado o compartilhamento de sessão - dois clientes se comunicando com o mesmo token -, a mesma é finalizada imediatamente, interrompendo a comunicação entre o servidor e o cliente.

04. DEMAIS INFORMAÇÕES

Para maiores informações acerca do protocolo OAuth2, o artigo disponível aqui traz informações mais abrangentes sobre o assunto.

05. ASSUNTOS RELACIONADOS

• OAuth2