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) : |
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:
- Sistema operacional 32 bits compatível (Microsoft Windows);
- Servidor web Apache 32 bits versão 2.4 (versão homologada: 2.4.47 e superiores);
- Servidor Redis versão 3.2 (versão homologada: 3.2.100 e superiores)
- 512 MB de memória RAM (mínimo);
- Processador 1,6 GHz (mínimo) e;
- 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:
# 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
# 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
# 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:
Arquivo | Parâmetro | Descrição | Valor padrão | Formato | Status |
---|---|---|---|---|---|
database.conf | CharSet | Conjunto de caracteres utilizado pelo banco de dados. | SQL_Latin1_General_CP1_CI_AS | Nenhum | Implementado |
database.conf | DriverID | Identificador do tipo de conexão com o banco de dados. | MSSQL | Nenhum | Implementado |
database.conf | Database | Nome do banco de dados a ser conectado. | sara_db | Nenhum | Implementado |
database.conf | Hostname | Nome do servidor e instância de instalação do banco de dados. | NOME_DO_SERVIDOR\INSTANCIA | ^[\w]+\\[\w]+$ | Implementado |
database.conf | Password | Senha do usuário de acesso ao banco de dados. | Nenhum | Nenhum | Implementado |
database.conf | Port | Porta de conexão com o banco de dados. | 1433 | 1~65535 | Implementado |
database.conf | Username | Nome do usuário de conexão com o banco de dados. | sa | Nenhum | Implementado |
session.conf | TokenTTL | Tempo de vida do token gerado pela API, em minutos. | 20 | 1~1440 | Implementado |
session.conf | RefreshTokenTTL | Tempo de vida do token de renovação gerado pela API. | 5 | 1~1440 | Implementado |
session.conf | CanRefreshBeforeExpirates | Flag que indica se o token de sessão pode ser atualizado antes da expiração | False | True/False | Implementado |
session.conf | TokenType | Indicador do tipo de token que será disponibilizado pela API. | Bearer | ^[\w]+[ ]{1}$ | Implementado |
license.conf | Server | Endereço do servidor de licenças. | Nenhum | IPv4/IPv6/Hostname | Implementado |
license.conf | LSPort | Porta de conexão com o servidor de licenças. | 5555 | 1~65535 | Implementado |
license.conf | Slot | Código do slot destinado ao ecossistema Recintos Aduaneiros. | 5078 | ^[\d]+$ | Implementado |
license.conf | ModuleID | ID do módulo do ecossistema (geralmente, o mesmo código do slot). | 5078 | ^[\d]+$ | Implementado |
license.conf | Language | Idioma para processamento das mensagens. | pt | ['pt','en','es'] | Implementado |
license.conf | LogFile | Arquivo de log dos registros de licença. | C:\TOTVS\log\OAuth2\LicenseManager_%s.log | ^[A-Z]{1}:\\([\w]+\\)+(LicenseManager_%s\.log)$ | Implementado |
license.conf | CNPJ | Número de CNPJ do cliente TOTVS Recintos Aduaneiros. | Nenhum | ^[\d]{14}$ | Implementado |
license.conf | RazaoSocial | Razã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.