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 a condições para o estabelecimento da sessão de usuário junto ao ecossistema Recintos Aduaneiros.
03. SOLUÇÃO
Como descrito no artigo sobre o modelo de sessão adotado para o TOTVS Recintos Aduaneiros, foi desenvolvida uma API RESTful que provê a estrutura necessária para a efetivação de sessões de usuário para utilização do sistema. Esta API foi desenvolvida como um módulo para o servidor web Apache (https://httpd.apache.org/), em sua versão 64 bits para sistemas operacionais Microsoft Windows e Linux de 64 bits. Isso facilita sua distribuição e implantação, versatilizando sua utilização. Por poder ser implantada em ambientes Linux, isso permite que ela seja abrigada em imagens Docker que rodem sob um container Kubernets, o qual pode gerenciar recursos de forma inteligente e prover uma alta escalabilidade para o serviço.
Sendo assim, para implantar e configurar a API OAuth2 é necessário possuir um servidor web Apache ativo e um servidor de banco de dados Redis instalado junto ao servidor web Apache, uma vez que os parâmetros de configuração e sessão estarão abrigados nele.
Para implantação da API OAuth2 é necessário:
- Sistema operacional 64 bits compatível (Linux/Microsoft Windows);
- Servidor web Apache 64 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.
A instalação da API em sistemas operacionais Linux depende, em todos os casos, da distribuição adotada. Em distribuições baseadas na distribuição Ubuntu, é necessário disponibilizar a API no diretório /usr/lib/apache2/modules, conforme imagem abaixo:
Além disso, é necessário criar os arquivos authentication.load e authentication.conf no diretório /etc/apache2/mods-available, conforme imagem abaixo:
O conteúdo do arquivo authentication.load é:
Arquivo authentication.load
LoadModule authentication_module modules/mod_authentication.so
Já o conteúdo do arquivo authentication.conf é:
Arquivo authentication.conf
<IfModule authentication_module>
<Location /api/sara/authentication/v1>
SetHandler mod_authentication-handler
</Location>
</IfModule>
Configuradas as opções de carregamento da API através do servidor web Apache, é necessário criar o arquivo de configuração da API em /etc/authentication/authentication.conf conforme indicado abaixo:
# Este é o arquivo de configuração da API de autenticação OAuth2 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 # caractere 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 instâ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 (criptografada) # Charset: Conjunto de caracteres utilizado pelo banco de dados CharSet SQL_Latin1_General_CP1_CI_AS DriverID MSSQL Database sara_db Hostname NOME_DO_HOST\NOME_DA_INSTANCIA Password SENHA_DO_USUARIO Port 1433 Username NOME_DO_USUARIO # Definições de parâmetros de sessão # # TokenTTL: Tempo de vida do token gerado pela API, em minutos # RefreshTokenTTL: Tempo de vida do token de atualização gerado pela API # CanRefreshBeforeExpirates: Flag que indica se o token de sessão pode ser atualizado antes da expiração # TokenTTL 20 RefreshTokenTTL 5 CanRefreshBeforeExpirates false
Com as configurações efetivadas, é necessário ativar o módulo da API através do comando abaixo:
$ sudo a2enmod authentication
E reiniciar o servidor web Apache através do comando abaixo:
$ sudo service apache2 restart
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 authentication_module modules/mod_authentication.so
<IfModule authentication_module>
<Location /api/sara/authentication/v1>
SetHandler mod_authentication-handler
</Location>
</IfModule>
Como parte da configuração da API, é necessário criar seu arquivo de configuração em C:\TOTVS\etc\authentication.conf com o conteúdo abaixo:
# Este é o arquivo de configuração da API de autenticação OAuth2 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 # caractere 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 instâ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 (criptografada) # Charset: Conjunto de caracteres utilizado pelo banco de dados CharSet SQL_Latin1_General_CP1_CI_AS DriverID MSSQL Database sara_db Hostname NOME_DO_HOST\NOME_DA_INSTANCIA Password SENHA_DO_USUARIO Port 1433 Username NOME_DO_USUARIO # Definições de parâmetros de sessão # # TokenTTL: Tempo de vida do token gerado pela API, em minutos # RefreshTokenTTL: Tempo de vida do token de atualização gerado pela API # CanRefreshBeforeExpirates: Flag que indica se o token de sessão pode ser atualizado antes da expiração # TokenTTL 20 RefreshTokenTTL 5 CanRefreshBeforeExpirates false
Tendo efetivado a construção do 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 o arquivo de configuração authentication.conf definindo seus parâmetros conforme abaixo:
| Conjunto | Parâmetro | Descrição | Valor padrão | Formato | Status |
|---|---|---|---|---|---|
| Banco de dados | CharSet | Conjunto de caracteres utilizado pelo banco de dados. | SQL_Latin1_General_CP1_CI_AS | Nenhum | Implementado |
| Banco de dados | DriverID | Identificador do tipo de conexão com o banco de dados. | MSSQL | Nenhum | Implementado |
| Banco de dados | Database | Nome do banco de dados a ser conectado. | sara_db | Nenhum | Implementado |
| Banco de dados | Hostname | Nome do servidor e instância de instalação do banco de dados. | NOME_DO_SERVIDOR\INSTANCIA | ^[\w]+\\[\w]+$ | Implementado |
| Banco de dados | Password | Senha do usuário de acesso ao banco de dados. | Nenhum | Nenhum | Implementado |
| Banco de dados | Port | Porta de conexão com o banco de dados. | 1433 | 1~65535 | Implementado |
| Banco de dados | Username | Nome do usuário de conexão com o banco de dados. | sa | Nenhum | Implementado |
| API | TokenTTL | Tempo de vida do token gerado pela API, em minutos. | 20 | 1~1440 | Em implementação |
| API | RefreshTokenTTL | Tempo de vida do token de renovação gerado pela API. | 5 | 1~1440 | Em implementação |
| API | CanRefreshBeforeExpirates | Flag que indica se o token de sessão pode ser atualizado antes da expiração | False | True/False | Em implementação |
É importante notar que entre os parâmetros e seus valores deve haver apenas espaço em branco. 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
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas