TOTVS Logística Recintos Aduaneiros

Árvore de páginas


01. DADOS GERAIS

Produto:

TOTVS Logística Recintos Aduaneiros

Linha de Produto:

Linha Logix

Segmento:

Logística

Módulo:Serviço de autenticação OAuth2
Função:Serviço de autenticação OAuth2
Ticket:
Requisito/Story/Issue (informe o requisito relacionado) :
  1. DLOGPORTOS-16564
  2. DLOGPORTOS-15882


02. SITUAÇÃO/REQUISITO

Para atendimento da demanda de autenticação, para o produto TOTVS Recintos Aduaneiros, através do protocolo OAuth2, foram estabelecidas as condições para o consumo apropriado de licenças de uso junto ao servidor de licenças do ecossistema Recintos Aduaneiros.

03. SOLUÇÃO

Com a implementação do modelo de autenticação via padrão OAuth2, baseado em módulos do servidor web Apache, foi necessária a implementação de ferramentas de consumo de licenças para garantir o efetivo controle do número de usuários simultâneos conectados à solução.

Para implantação da API OAuth2 é necessário:

  1. Sistema operacional 32 bits compatível (Microsoft Windows);
  2. Servidor web Apache 32 bits versão 2.4 (versão homologada: 2.4.47 e superiores);
  3. Servidor Redis versão 3.2 (versão homologada: 3.2.100 e superiores)
  4. 512 MB de memória RAM (mínimo);
  5. Processador 1,6 GHz (mínimo) e;
  6. 25 MB de espaço disponível em disco.



Para implantação da API em servidores com sistema operacional Microsoft Windows é necessário disponibilizar seu módulo no diretório de módulos da instalação do servidor web Apache, conforme imagem abaixo:

Após a disponibilização do arquivo, é necessário editar o arquivo httpd.conf constante na instalação do servidor web Apache, acrescentando as linhas a seguir:

LoadModule totvsauth_v1_module modules/mod_totvsauth_v1.so

<IfModule totvsauth_v1_module>
  <Location /api/sara/authentication/v1>
    SetHandler mod_totvsauth_v1-handler
  </Location>
  LoadFile C:/windows/SysWOW64/license_client.dll
</IfModule>

Como parte da configuração da API, é necessário criar seus arquivos de configuração em C:\TOTVS\etc\SARA\OAuth2 com os conteúdos abaixo:

database.conf
# Este é o arquivo de configuração da conexão com o banco de dados do 
# ecossistema Recintos Aduaneiros. Assim como o arquivo de configuração
# do Apache, as configurações aqui seguem o padrão "chave valor",
# sendo assim, tanto chaves quanto valores contém uma única palavra.
#
# Comentários podem ser feitos adicionando o símbolo # como primeiro
# caracter da linha. Isso também pode ser utilizado para desativar
# configurações.

# Definições de acesso ao banco de dados 
#
# DriverID: Driver utilizado para a conexão com o banco de dados
# Server: Nome do servidor onde a intância do banco de dados está instalada
# Port: Porta pela qual o banco de dados pode ser acessado
# Name: Nome do banco de dados a ser acessado
# User: Nome do usuário de acesso ao banco de dados
# Password: Senha usada pelo usuário para acesso ao banco de dados
# Charset: Conjunto de caracteres utilizado pelo banco de dados

CharSet=SQL_Latin1_General_CP1_CI_AS
DriverID=MSSQL
Database=sara_db
Hostname=JVN060104925\DEVELOPER
Password=TOTVS@123456
Port=1433
Username=sa
session.conf
# Este é o arquivo de configuração dos parâmetros de sessão.
# Aqui é possível configurar os parâmetros de tempo de vida e
# renovação do token de sessão do usuário. Assim como o arquivo 
# de configuração do Apache, as configurações aqui seguem o 
# padrão "chave valor", sendo assim, tanto chaves quanto valores
# contém uma única palavra.
#
# Comentários podem ser feitos adicionando o símbolo # como primeiro
# caracter da linha. Isso também pode ser utilizado para desativar
# configurações.

# Definições dos parâmetros de sessão
#
# TokenTTL: Tempo de vida do token de sessão, em minutos.
# TokenType: Indicador do tipo de token a ser gerado.
# RefreshTokenTTL: Tempo de vida do token de renovação de sessão, em minutos.
# CanRefreshBeforeExpires: Flag que indica se o token de renovação pode ser utilizado antes do fim da sessão.

TokenTTL=20
TokenType=Bearer
RefreshTokenTTL=5
CanRefreshBeforeExpires=true
license.conf
# Este é o arquivo de configuração de consumo de licenças.
# O formato de armazenamento dos valores de configuração
# para acesso ao servidor de licenças segue o padrão
# "chave=valor", assim como os demais arquivos de configuração
# dos demais aspectos do ambiente. Sendo assim, tanto chaves
# quanto valores contém uma única palavra.
#
# Comentários podem ser feitos adicionando o símbolo # como primeiro
# caracter da linha. Isso também pode ser utilizado para desativar
# configurações.
#
# Definições de acesso ao servidor de licenças:
#
# Server: nome de rede ou endereço IP do servidor de licenças
# Port: porta pela qual o servidor de licenças atende às requisições
# Slot: número do slot reservado para o produto no servidor
# Language: indicador de idioma das mensagens
# LogFile: arquivo de log para registro dos movimentos de licença
# CNPJ: Número de inscrição do cliente junto ao Cadastro Nacional de Pessoas Jurídicas
# RazaoSocial: Razão Social pela qual o cliente está registrado

Server=jv-sara-tst01
LSPort=5555
Slot=5078
ModuleID=5078
Language=pt
LogFile=C:\TOTVS\log\OAuth2\LicenseManager_%s.log
CNPJ=17227422000520
RazaoSocial=GERDAU

Tendo efetivado a construção dos arquivo de configuração da API, é necessário reiniciar o servidor web Apache através de seu gestor de serviços ou o gestor de serviços do sistema operacional.

Para configuração da API OAuth2, é necessário editar os arquivos de configuração, definindo seus parâmetros conforme abaixo:

ArquivoParâmetroDescriçãoValor padrãoFormatoStatus
database.confCharSetConjunto de caracteres utilizado pelo banco de dados.SQL_Latin1_General_CP1_CI_ASNenhumImplementado
database.confDriverIDIdentificador do tipo de conexão com o banco de dados.MSSQLNenhumImplementado
database.confDatabaseNome do banco de dados a ser conectado.sara_dbNenhumImplementado
database.confHostnameNome do servidor e instância de instalação do banco de dados.NOME_DO_SERVIDOR\INSTANCIA^[\w]+\\[\w]+$Implementado
database.confPasswordSenha do usuário de acesso ao banco de dados.NenhumNenhumImplementado
database.confPortPorta de conexão com o banco de dados.14331~65535Implementado
database.confUsernameNome do usuário de conexão com o banco de dados.saNenhumImplementado
session.confTokenTTLTempo de vida do token gerado pela API, em minutos.201~1440Implementado
session.confRefreshTokenTTLTempo de vida do token de renovação gerado pela API.51~1440Implementado
session.confCanRefreshBeforeExpiratesFlag que indica se o token de sessão pode ser atualizado antes da expiraçãoFalseTrue/FalseImplementado
session.confTokenTypeIndicador do tipo de token que será disponibilizado pela API.Bearer ^[\w]+[ ]{1}$Implementado
license.confServerEndereço do servidor de licenças.NenhumIPv4/IPv6/HostnameImplementado
license.confLSPortPorta de conexão com o servidor de licenças.55551~65535Implementado
license.confSlotCódigo do slot destinado ao ecossistema Recintos Aduaneiros.5078^[\d]+$Implementado
license.confModuleIDID do módulo do ecossistema (geralmente, o mesmo código do slot).5078^[\d]+$Implementado
license.confLanguageIdioma para processamento das mensagens.pt

['pt','en','es']

Implementado
license.confLogFileArquivo de log dos registros de licença.C:\TOTVS\log\OAuth2\LicenseManager_%s.log

^[A-Z]{1}:\\([\w]+\\)+(LicenseManager_%s\.log)$

Implementado
license.confCNPJNúmero de CNPJ do cliente TOTVS Recintos Aduaneiros.Nenhum

^[\d]{14}$

Implementado
license.confRazaoSocialRazão social do cliente TOTVS Recintos Aduaneiros.Nenhum

^[\w]+$

Implementado

É importante notar que entre os parâmetros e seus valores deve haver apenas um sinal de igualdade ("="). Se esta regra não for obedecida, a configuração adotará o valor padrão por considerar inválida a opção.

Após implantada e configurada, a API responderá conforme o endereço exposto pelo servidor (Ex.: https://localhost/api/sara/authentication/v1/session/token). Assim como é definido no protocolo OAuth2, as requisições devem ser feitas através do método POST, com formato application/x-www-form-urlencoded, conforme imagem abaixo, para uma solicitação Password Grant:

Para solicitações Client Credentials, deve-se solicitar conforme imagem abaixo:

É possível configurar, através do aplicativo Postman, as credenciais para acesso à API e obtenção, uso e renovação do token de sessão, conforme imagens abaixo:

Caso haja uma tentativa de renovação do token de sessão antes do período permitido - caso o parâmetro CanRefreshBeforeExpirates esteja setado como false -, a API emitirá um erro 401 (Unauthorized), conforme imagem abaixo:

E, no caso de todos os requisitos serem satisfeitos para a renovação, a API responderá com um novo conjunto de tokens, conforme imagem abaixo:


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