Informações Relevantes sobre HTTP/REST no MeuRH

01. Seção SSLCONFIGURE

• Durante a configuração do dessa tag em seu 'appserver.ini' observe as validações do seu certificado e quais são os níveis de criptografia que permite a utilização.
• Após estar tudo funcionando é indicado desabilitar o 'verbose' para evitar a atualização/gravação de mensagens informativas em seu 'console.log' o que pode afetar a performance do server.
• Informe seu certificado e chave privada do seu certificado de acordo com as informações abaixo e também detalhadas no caso de uso do tópico anterior.
• É importante habilitar também as palavras reservadas 'SSL' , pois sem estarem habilitadas as APIs REST não responderão, pois o modelo de criptografia utilizada será automaticamente definida entre browsers e server baseado no certificado utilizado e nas versões de browsers do cliente, também não podem existir gaps entre os modelos de criptografia, por exemplo, não é permitido pular o modelo, colocando SSL2=1 ; SSL3=0; TLS1=1.  
• As tags corretas para declaração dos arquivos de certificados para essa chave são "Certificate" e "key". 
• Não deixe de informar a 'PassPhrase', ou palavra/frase passe, pois ela é sua segurança para inibir acesso as informações de seu certificado utilizando função da Tech, como por exemplo a função PEMInfo() 

[SSLConfigure]
Enable=1
SSL2=1
SSL3=1
TLS1=1
TLS1_0=1
TLS1_1=1
TLS1_2=1
verbose=0
Certificate=c:\totvs\certificate.crt
Key=c:\totvs\private.key
PassPhrase=meurhpwd

02. Sobre Configuração do REST

Referente a configurações básicas para o serviço REST já foram comentadas no processo de instalação, sendo assim, vamos compartilhar outras informações relevantes sobre esse serviço que podem estar ligadas a sua infra-estrutura e a arquitetura do App MeuRH.

• Inicialmente é importante ressaltar que problemas encontrados no certificado, como por exemplo, carregar em ambiente 'não seguro', poderá não funcionar o processo de login no aplicativo pelo celular, visto existem restrições de segurança de cada sistema operacional mobile, mesmo que o funcionamento ocorra normalmente pelo browser, onde nesse caso temos a possibilidade de permitir manualmente a habilitação do carregamento para URLs não seguras.
  
  
• Provavelmente o seu serviço de APIs REST estará instalado em um servidor que responda a um IP Externo, consequentemente não faz sentido subir uma porta do REST que não possua o seu certificado SSL:
  • Caso deseje configurar uma API apenas com HTTP indicamos subir e utilizar um appserver apenas em um servidor físico em sua rede local.
  • Ao utilizar o SSL verifique as características do seu certificado baseado nas informações dos tópicos anteriores.
• A palavra 'URL' dentro da tag [HTTPENV] deverá possuir inicialmente o conteúdo "/rest", pois é obrigatória para a utilização da arquitetura do App MeuRH, principalmente quando utilizada pelo celular:
  • Após a palavra "/rest" você poderá informar quaisquer nomes para compor a sua URL de APIs, em nosso caso de uso nossa URL ficaria por exemplo: https://104.210.222.191:8107/restT1
  • Entretanto, por nosso certificado criado não estar habilitado para esse IP público estaremos utilizando o serviço REST sem ssl para esse ambiente de teste, respondendo apenas em http://104.210.222.191:8107/rest
  • Sendo assim, apenas foi retirado as informações referente ao certificado da tag [HTTPREST].  
• Referente a seção [RESTCONFIG], ela é criada exclusivamente para utilização da arquitetura do App MeuRH:
  • A palavra 'restPort'  é utilizada pelos serviços de backend por isso a obrigatoriedade do seu preenchimento, sendo assim, apesar do protheus em seu appserver permitir que se possa instanciar várias portas REST, em virtude da arquitetura do meurh esse contexto não é permitido.
  • Em relação a palavra reservada 'MeuRHLog' ela auxilia no processo de login e manutenção para identificar possíveis dificuldades no processo de configuração e divergências de login, posteriormente, também pode ser desligada utilizando o valor '0' para melhorar a performance de resposta do aplicativo.
• Não deixe de confirmar se a porta do serviço REST utilizada está liberada em seu firewall para permitir receber as requisições.
• As tags corretas para declaração dos arquivos de certificados dentro do serviço REST são "CertificateServer" e "keyServer".
• Por questões de compatibilidade do protocolo de criptografia não deixe de informar essa tag "TLS1=3" no seu serviço REST.   
• Não deixe também de habilitar o item 'SECURITY', pois ele é responsável em exigir as autenticações para a utilização das API´s, caso não estejam ligados o server responderá qualquer requisição recebida sem validação.

[HTTPV11]
ENABLE=1
Sockets=HTTPREST

[HTTPREST]
Port=8107
SECURITY=1
URIs=HTTPENV
SSL2=1
SSL3=1
TLS1=3
TLS1_0=1
TLS1_1=1
TLS1_2=1
verbose=0
CertificateServer=c:\totvs\certificate.crt
KeyServer=c:\totvs\private.key
PassPhrase=meurhpwd

[HTTPENV]
URL=/rest
PrepareIn=T1
Instances=2,1
ENVIRONMENT=12.1.27
Public=fwjwt/refresh_token,auth
CORSEnable=1
AllowOrigin=*

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=12.1.27

[ONSTART]
JOBS=HTTPJOB

[RESTCONFIG]
restPort=8107
MeuRHLog=1

03. Sobre Configuração da Seção HTTP & HTTPs

Em relação as configurações de hosts HTTP no seu 'appserver.ini', essas informações abaixo são importantes e complementares ao processo de instalação:

• É obrigatório a informação da tag mesmo que você deseje utilizar apenas utilizar o serviço HTTPs, entretanto, você desabilitar com 'enable=0' para que nenhuma requisição seja respondida por qualquer host configurado.
• As tags corretas para declaração dos arquivos de certificados no HTTPs são "Certificate" e "key".
• É importante configurar adequadamente a tag "PATH" ela é responsável de restringir que o serviço HTTP possa permitir acesso a outras pastas que estejam fora do caminho informado, no exemplo abaixo, apenas as sub-pastas de \web estarão acessíveis.  
• Por padrão web e também do server protheus é importante relembrar que por padrão utilizando o protocolo HTTP a porta padrão é 80, enquanto utilizando HTTPs a porta padrão é 443.
  • A utilização de portas diferentes irá obriga-lo a configura-las nos hosts/urls, veja no próximo tópico.
• Lembre-se de liberar as portas utilizadas em seus serviços de firewall em seu servidor.
• Procure utilizar a palavra reservada 'compression', essa funcionalidade realiza automaticamente no server uma compressão gzip nos arquivos que serão enviados e os browsers já fazem essa descompactação do arquivos, assim os processos de transferência/download e inicialização ficam mais rápidos.
• Caso realizem alguma configuração para esconder URLs quando a utilização ocorrer via browsers através de iframe é necessário configurar e informar a palavra reservada 'xFrameOptions'.

[HTTP]
ENABLE=0
PATH=C:\Protheus_12127\Protheus_data\web
PORT=80
ENVIRONMENT=12.1.27
XFrameOptions = ALLOW-FROM http://meurh.world
Compression=1

[HTTPS]
ENABLE=1
PATH=C:\Protheus_12127\Protheus_data\web
PORT=443
ENVIRONMENT=12.1.27
XFrameOptions = ALLOW-FROM http://meurh.world
Compression=1
VERBOSE=1
SSL2=1
SSL3=1
TLS1=1
TLS1_0=1
TLS1_1=1
TLS1_2=1
Certificate=C:\Protheus_12127\bin\appserver\meurh_certificate.crt
Key=C:\Protheus_12127\bin\appserver\meurh_private.key
PassPhrase=2020MeuRH#pwd

04. Sobre Configuração de Hosts/Seções HTTP

• Os Hosts são as suas URLs disponíveis que são responsáveis em trafegar as seus arquivos clients declarados na palavra passe 'path', sendo assim para cada URL será necessário uma declaração em seu 'appserver.ini'.
• Em relação a utilização e declaração de uma URL como host é necessário realizar a publicação desse subdomínio com seu respectivo IP Externo nos servidores DNS, no provedor de internet caso não possua um servidor de publico na sua empresa. Do contrario será possível acessar diretamente pelo browser apenas o seu endereço IP Externo
• Sobre a utilização de outras portas para HTTP, além das portas padrões comentadas no item anterior desse documento, será necessário inclui-las na composição do seu host, exemplo:
  • Caso tenha declarado que a porta do seu HTTP será 8080 ou HTTPs como 8433.
  • Precisará configurar a respectiva porta em seu host, ficando [104.210.222.191:8080]  ou  [104.210.222.191:8433] 
  • Consequente em seu browser deverá ser acessado http://104.210.222.191:8080 ou  https://104.210.222.191:8433
• Outra informação relevante é que caso tenha caso tenha informado algum identificador posteriormente ao nome da URL Rest configurada, em virtude da arquitetura de utilização via aplicativo no celular será necessário incluir esse complemento na declaração do seu host, exemplo:
  • Supondo que tenha informado na sua configuração do REST 'URL=/restT1'
  • A sufixo T1 deverá estar composto na declaração de sua URL [104.210.222.191/T1] , sendo assim o seu acesso deverá ser feito pelo browser como https://104.210.222.191/T1
    
    

[portal.meurh.world]
ENABLE=1
PATH=C:\Protheus_12127\Protheus_data\web\PortalMeuRH
DEFAULTPAGE=index.html

[104.210.222.191]
ENABLE=1
PATH=C:\Protheus_12127\Protheus_data\web\PortalMeuRH
DEFAULTPAGE=index.html

05. Sobre Utilização e Configuração de Multi-Empresas

• Quando estamos falando de multi-empresas ou grupo de empresas separadas falamos sobre dicionarios separados, por exemplo SX2T10 e SX2T20, para esses casos nossa indicação inicial é utilizar um appserver para cada empresa, podendo ser no mesmo servidor, isso facilita algum tipo de manutenção e controle se necessário.
  • Por exemplo, é possível configurar um appserver apenas com as seção do REST sem a seção HTTP que poderá estar localizado em outro appserver servindo as mesma porta. Enfim são muitas possibilidades de configuração, mas algumas podem sofrer restrições em virtude da arquitetura de conexão do aplicativo.
  • Modelos diferenciados de configuração necessitam uma revisão do arquivo 'properties.json' e da geração do QRCode para conexão.
• Em relação ao serviço REST, em virtude da arquitetura do aplicativo, não recomendamos utilizar a palavra reservada "prepareIn=ALL".
  • Apesar do serviço ter a possibilidade de subir threads utilizando essa opção, o processo de autenticação do backend exige URLs Rest separadas, pois em alguns casos sua requisição pode cair no server em uma thread de outra empresa, pois no momento da requisição não existe a identificação do Tenent que deseja acessar.

Todavia é possível configurar empresas simultaneamente no mesmo appserver, então abaixo indicaremos como é possível indicar essa informações:

•  Inicialmente você deve configurar duas seções de environment (URIs) para as APIs Rest, uma para cada empresa, de acordo com o exemplo abaixo:
  • Pode-se utilizar a mesma porta REST para os dois ambientes, no caso port=8107.
  • Observe q temos as URLs  /restT1  &  /restT2, consequentemente serão responderão como  http://104.210.222.191:8107/restT1   &  http://104.210.222.191:8107/restT2

[HTTPV11]
ENABLE=1
Sockets=HTTPREST

[HTTPREST]
Port=8107
SECURITY=1
URIs=HTTPENVT1,HTTPENVT2

[HTTPENVT1]
URL=/restT1
PrepareIn=T1
Instances=2,5,1,1
Public=fwjwt/refresh_token,auth
CORSEnable=1
AllowOrigin=*

[HTTPENVT2]
URL=/restT2
PrepareIn=T2
Instances=2,5,1,1
Public=fwjwt/refresh_token,auth
CORSEnable=1
AllowOrigin=*

• Posteriormente necessitamos atualizar as seções/hosts com as URLs HTTP:
  • Referente a configuração dessas seções podemos encontrar mais detalhes no item anterior 4 desse documento.
  • Para esse caso devemos atualizar o host,complementando com o sufixo informado após a palavra 'rest' contido na tag URL=/restT1 para cada empresa definida.
  • Outra informação importante é a necessidade de duplicar a pasta dos arquivos client criada na tag PATH, em virtude das alterações a serem feitas individualmente no arquivo 'properties.json', temos um exemplo no próximo tópico.
  • Esse contexto de configuração implica na necessidade de geração de QRCodes separados para cada empresa:
    • Como no exemplo, o QRCode para primeiro host / URL deve ser: https://104.210.222.191/T1/?restPort=8103 

[104.210.222.191/T1]
ENABLE=1
PATH=C:\Protheus_12127\Protheus_data\web\PortalMeuRHT1
DEFAULTPAGE=index.html

[104.210.222.191/T2]
ENABLE=1
PATH=C:\Protheus_12127\Protheus_data\web\PortalMeuRHT2
DEFAULTPAGE=index.html

• Para utilização de diferentes portas para HTTP diferentes dos padrões (80 & 443), devemos:
  • Devemos incluí-la no endereço do host, conforme exemplo abaixo utilizando a nova porta 8443.
  • Esse modelo também afeta a composição do QRCode a ser gerado, nesse caso deve ser: https://104.210.222.191:8443/T1/?restPort=8103  
  • A inclusão dessa nova porta não afeta as configurações do arquivo 'properties.json'.

[104.210.222.191:8443/T1]
ENABLE=1
PATH=C:\Protheus_12127\Protheus_data\web\PortalMeuRHT1
DEFAULTPAGE=index.html

06. Sobre Configuração do Properties.json

O configuração do arquivo 'properties.json', que se localiza dentro da pasta informada em seu host/url, é fundamental para a correta conexão aos serviços de sua API Rest, eventualmente pode acontecer de funcionar corretamente o acesso pelo browser, todavia a tentativa de conexão/login quando utilizada pelo celular não funciona adequadamente.

Diferentes modelos de configuração podem influenciar diretamente em como esse arquivo será composto, basicamente nesse json temos dois campos a serem preenchidos 'baseUrl' & 'rootContext', sendo assim abaixo teremos algumas opções para a elaboração desse arquivo.

• Para modelos de configuração sem utilização de SSL e sem complemento para o endereço do serviço rest ( URL=/rest  ), teremos as seguintes informações:
  •  "baseUrl": "http://104.210.222.191:8107/rest",
  • "rootContext": ""
    
    
• Para modelos de configuração sem utilização de SSL e com complemento para o endereço do serviço rest ( URL=/rest T1 ), teremos as seguintes informações:
  •  "baseUrl": "http://104.210.222.191:8107/restT1",
  • "rootContext": "/T1/"

• Para modelos de configuração com utilização de SSL e sem complemento para o endereço do serviço rest ( URL=/rest  ), teremos as seguintes informações:
  •  "baseUrl": "https://104.210.222.191:8107/rest",
  • "rootContext": ""
    
    
• Para modelos de configuração com utilização de SSL e com complemento para o endereço do serviço rest ( URL=/restT1  ), teremos as seguintes informações:
  •  "baseUrl": "https://104.210.222.191:8107/restT1",
  • "rootContext": "/T1/"