• O que é o WebAgent

• Pensado pra ser seguro

• Vantagens no uso do WebAgent em conjunto com o WebApp

• Porque não devemos compartilhar a mesma sessão do WebAgent entre dois usuários do Windows?

• Instalação

  • Para o administrador do sistema

    • Validando os instaladores do WebAgent (Hash)

    • Configurando o download do WebAgent a partir do arquivo AppServer.INI

    • Configurando o download do WebAgent a partir do arquivo WebAgent.json

    • Configurando uma porta específica para o WebAgent de todos os usuários

    • Atualização automática de arquivos extras, exemplo, SIGALOJA.DLL

  • Para o usuário do ERP: Baixando o instalador para seu SO

    • Instalando no Windows

    • Instalando no Linux

    • Instalando no macOS

• Registrando o certificado SSL para uso do WebAgent

  • Para usuários Windows (automático)

  • Para usuários Linux (automático a partir da versão 1.0.15)

  • Para usuários macOS

• Habilitando o WebAgent na Tela de Parâmetros

• Executando o WebAgent em linha de comando

  • Comando launch: Abrindo o navegador diretamente pelo WebAgent

  • Comando --headless: Executando aplicações sem interface através do WebAgent

  • Comando --kiosk: Executando o ERP em tela cheia (fullscreen)

• Entendendo as arquiteturas 32 e 64 bits para uso do WebAgent

• Exemplos de integração utilizando o WebAgent

• Sistemas Operacionais homologados

• Sistemas Operacionais em homologação

O vídeo a seguir demonstra a configuração básica e um teste de uso do WebAgent, para facilitar o entendimento sobre a ferramenta.

O que é o WebAgent (topo)

O WebAgent é um serviço opcional necessário "apenas" nas estações de trabalho que precisem utilizar:

• Leitura e gravação de arquivos locais;
• Integração com o pacote Microsoft Office;
• Integração com DLLs (Windows), SOs (Linux) e Dylibs (macOS), mais informações consulte ExecInDllOpen.

Pensado pra ser seguro (topo)

Os navegadores atuais possuem um ambiente de execução segura, chamado Sandbox, que impede o acesso à sua estação de trabalho.

O WebAgent permite esses acessos de forma segura, utilizando os seguintes mecanismos:

• Conexão entre o navegador e o WebAgent exclusivamente via Websocket Secure (wss);
• Conexão entre o navegador e o WebAgent exclusivamente através do endereço localhost, bloqueando ataques a partir de IPs externos;
• Uso do mesmo protocolo de comunicação utilizado entre SmartClient Desktop e o Appserver, um motor utilizado a mais de 20 anos, e conhecidamente seguro.

Vantagens no uso do WebAgent em conjunto com o WebApp (topo)

• Simplificação na montagem de ambientes;
• Instalação simples e rápida, devido ao menor numero de arquivos do WebAgent;
• Ambiente HTML (navegador) sempre atualizado, preparado para os mais novos Frameworks HTML de mercado.

Porque não devemos compartilhar a mesma sessão do WebAgent entre dois usuários do Windows? (topo)

Como descrito na imagem abaixo (clique na imagem para melhor visualização), quando dois ou mais usuários compartilham a mesma estação de trabalho Windows, não é seguro manter uma instância do WebAgent aberta ao se efetuar o logout.

Isso irá comprometer a execução de qualquer função que retorne dados do usuário, como por exemplo, a função GetCredential, que irá retornar informações do usuário que instanciou o WebAgent, e que não necessariamente é o usuário atual desta estação.

O procedimento obrigatório para estações compartilhadas é utilizar o parâmetro Launch, mais informações clique aqui, ele irá iniciar um WebAgent em uma porta efêmera (temporária), irá iniciar automaticamente o navegador para o usuário, e irá se auto encerrar 2 a 3 minutos após este navegador ser fechado pelo usuário.

Mesmo que o usuário mantenha o WebAgent instanciado via Launch em sua sessão Windows, o fato de estar sendo executado em uma porta única irá garantir a segurança desta operação.

Instalação (topo)

Para o administrador do sistema (topo)

Baixe os instaladores do WebAgent a partir da Central de Downloads.

Validando os instaladores do WebAgent (Hash) (topo)

Os instaladores do WebAgent, mais especificamente as versões 32 bits para Windows, têm sido identificados como vírus pelo Windows Defender e outros antivírus. Isso se deve à natureza desta ferramenta, que provê acesso aos usuários à ferramentas como Microsoft Office e DLLs.

Abrimos chamados recorrentes para a Microsoft para que os instaladores sejam inseridos na lista de confiança.

Para garantir maior segurança dos ambientes, a partir do WebAgent 1.0.23 passaremos a distribuir junto ao Zip/Tar.gz arquivos texto contendo o Hash destes instaladores, e abaixo explicaremos como validar esses arquivos da maneira correta.

Vale ressaltar que os instaladores para Windows já são assinados, e a validação pelo Hash se torna um segundo modelo de verificação.

Validando os instaladores para Windows

Copie o conteúdo do trecho abaixo em um arquivo com o nome verify_hash_windows.ps1

🚨Para execução deste Script pode ser necessária autorização de Admin ao seu sistema.

# Sintaxe
# .\verify_hash_windows.ps1 <caminho para o arquivo> <hash>

if ((Get-FileHash "$($args[0])").Hash -eq "$($args[1])") {
  Write-Host "Hash verificado com Sucesso (Hash verified successfully)"
} else {
  Write-Host "Hash falhou, verifique o arquivo (Hash failed, check the file)"
}

Abra o PowerShell e execute o comando, seguindo a sintaxe:

.\verify_hash_windows.ps1 <caminho para o arquivo> <hash>

Exemplo:

.\verify_hash_windows.ps1 webagent.msi aa20bf29249a78c71357a394c5083dc57ee4109a8d3fd2d6edb9dbf734e6936f

Se for exibida a mensagem "Hash verificado com Sucesso", pode proceder com a liberação do instalador aos seus usuários.

Se for exibida a mensagem "Hash falhou, verifique o arquivo", entre em contato imediatamente com o Suporte da TOTVS.

Validando os instaladores para Linux/macOS

Copie o conteúdo do trecho abaixo em um arquivo com o nome verify_hash_linux_mac.sh

🚨Para execução deste Script pode ser necessária autorização de Admin ao seu sistema.

# Sintaxe
# ./verify_hash_linux_mac.sh <caminho para o arquivo> <hash>

if [ "$(sha256sum $1 | awk '{print $1}')" == "$2" ]; then
  echo "Hash verificado com Sucesso (Hash verified successfully)"
else
  echo "Hash falhou, verifique o arquivo (Hash failed, check the file)"
fi

Abra o console e habilite a execução do Script através do comando:

chmod +x verify_hash_linux_mac.sh

Na sequência execute o comando, seguindo a sintaxe:

./verify_hash_linux_mac.sh <caminho para o arquivo> <hash>

Exemplo:

./verify_hash_linux_mac.sh web-agent-1.0.23.deb c74dd24cbcaa5e49d511d0a740f10a43e628ae92ca49f7eda7ac90bbe9802502

Se for exibida a mensagem "Hash verificado com Sucesso", pode proceder com a liberação do instalador aos seus usuários.

Se for exibida a mensagem "Hash falhou, verifique o arquivo", entre em contato imediatamente com o Suporte da TOTVS.

Configurando o download do WebAgent a partir do arquivo AppServer.INI (topo)

Para consultar todas as opções de configuração acesse aqui.

Os parâmetros abaixo representam o Sistema Operacional e a Arquitetura(32/64 bits) do WebAgent:

[WEBAGENT]
VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
Windows_x86=webagent/web-agent-1.x.x-windows-x86.setup.exe
Windows_x64=webagent/web-agent-1.x.x-windows-x64.setup.exe
Darwin_universal=webagent/web-agent-1.x.x-darwin-universal.dmg
Linux_x64_deb=webagent/web-agent-1.x.x-linux-x64.deb
Linux_x64_rpm=webagent/web-agent-1.x.x-linux-x64.rpm

[WEBAGENT]
VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
Windows_x86=C:\totvs\files\web-agent-1.x.x-windows-x86.setup.exe
Windows_x64=C:\totvs\files\web-agent-1.x.x-windows-x64.setup.exe
Darwin_universal=C:\totvs\files\web-agent-1.x.x-darwin-universal.dmg
Linux_x64_deb=C:\totvs\files\web-agent-1.x.x-linux-x64.deb
Linux_x64_rpm=C:\totvs\files\web-agent-1.x.x-linux-x64.rpm

Configurando o download do WebAgent a partir do arquivo WebAgent.json (topo)

Neste exemplo utilizaremos o arquivo de configuração com o nome webagent.json, na mesma pasta do AppServer, mas tanto o nome do arquivo quanto o diretório são de sua escolha, ajuste a configuração de acordo com sua necessidade, por exemplo:

agentJsonUpdate=/home/admin/file_config/installers.json

Para definir o caminho dos instaladores inclua o parâmetro agentJsonUpdate na seção [WebApp] em seu arquivo AppServer.INI.

[WEBAPP]
Port=5002
agentJsonUpdate=webagent.json

Criando o arquivo WebAgent.json

Seguindo nosso exemplo, crie agora o arquivo webagent.json na mesma pasta do AppServer.

Os arquivos para download serão disponibilizados em uma subpasta do AppServer, exemplo: /home/admin/totvs/appserver/webagent/

{
    "version": "1.x.x","<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
    "windows_x86": "webagent\\web-agent-1.x.x-windows-x86-release.setup.exe",
    "windows_x64": "webagent\\web-agent-1.x.x-windows-x64-release.setup.exe",
    "darwin_universal": "20-10-10-p12_smartclient_web-agent_1.x.x_mac-universal.dmg",
    "linux_x64_deb": "webagent\\web-agent.deb",  
    "linux_x64_rpm": "webagent\\web-agent.rpm"
}

{
    "version": "1.x.x", "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
    "windows_x86": "webagent/web-agent-1.x.x-windows-x86-release.setup.exe",
    "windows_x64": "webagent/web-agent-1.x.x-windows-x64-release.setup.exe",
    "darwin_universal": "20-10-10-p12_smartclient_web-agent_1.x.x_mac-universal.dmg",
    "linux_x64_deb": "webagent/web-agent.deb",  
    "linux_x64_rpm": "webagent/web-agent.rpm"
}

Configurando uma porta específica para o WebAgent de todos os usuários (topo)

[WEBAGENT]
Port=21021
...

Ao habilitar essa chave, a opção "Habilita/Desabilita o Agente Local" não será mais exibida na tela de configuração para o usuário.

Atualização automática de arquivos extras, exemplo, SIGALOJA.DLL (topo)

A partir do WebAgent 1.0.15 e WebApp 10.0.6 (apenas Onça Preta), é possivel definir a atualização automática de arquivos extras, como por exemplo, os arquivos do FrontLoja.

As chaves a seguir definem o caminho para um arquivo ZIP, que deverá conter a estrutura de diretórios e arquivos que o cliente deseja descompactar na pasta do WebAgent.

📢 Estas chaves estão disponiveis tanto no arquivo AppServer.INI quanto no arquivo JSON de configuração.

[WEBAGENT]
VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
Windows_x86=C:\totvs\files\web-agent-1.x.x-windows-x86.setup.exe
Windows_x64=C:\totvs\files\web-agent-1.x.x-windows-x64.setup.exe
Windows_x86_extras=C:\totvs\files\DLL_SIGALOJA_Win32.zip
Windows_x64_extras=C:\totvs\files\DLL_SIGALOJA_Win64.zip

Para o usuário do ERP (topo)

Acessando a Tela de Parâmetros do WebApp, agora será exibida a tela para download dos instaladores:

O instalador vai sugerir o Sistema Operacional e a Arquitetura(32/64 bits).
Caso utilize o Windows 64 bits, mas precise integrar o ERP com o Microsoft Office 32 bits, poderá baixar o WebAgent 32 bits, mais detalhes aqui.

Instalando no Windows (topo)

Após o download do instalador, basta iniciar sua instalação, que irá seguir sem intervenção do usuário.

O programa ficará disponível no menu, como neste exemplo utilizando o Windows 11.

O WebApp irá iniciar o WebAgent sempre que necessário, mais detalhes consulte a seção Habilitar WebAgent na Tela de Parâmetros.

Apenas para testes, você pode iniciar o WebAgent manualmente, ele será exibido na bandeja de ícones:

Instalando no Linux (topo)

Para mais detalhes sobre como baixar o WebAgent acesse aqui, escolha o download para o seu Linux, sendo o arquivo .deb para Ubuntu e o .rpm para o Fedora, Oracle Linux e Red Hat.

Video com detalhes do processo:

Ubuntu

sudo apt install ./web-agent<versao>.deb

chmod +x ./web-agent<versao>.deb

Fedora, Oracle Linux

sudo dnf install oracle-epel-release-el9
sudo dnf update

sudo dnf install libappindicator-gtk3

sudo dnf install gnome-extensions-app gnome-shell-extension-appindicator 

🚨 Importante: Efetue o logout e se logue novamente no sistema operacional para efetivar a instalação da extensão acima.

Acesse o aplicativo Extensões

Habilite a extensão AppIndicator

sudo dnf install ./web-agent<versao>.rpm

chmod +x ./web-agent<versao>.deb

Instalando no macOS (topo)

Este exemplo de instalação/autorização se baseia no macOS Sequoia. (💡 Dica: Clique nas imagens para melhor visualização )

Após baixar o arquivo de instalação para macOS (Universal), com a extenção .dmg, execute o instalador e na sequencia arraste o web-agent para pasta Aplicações (Applications)

Caso esteja atualizando o web-agent, pressione o botão Atualizar (Replace)

Abra o web-agent na pasta Aplicações e pressione o botão Done

Acesse as configurações do seu Mac e na sequencia Privacidade e Segurança (Privacy & Security)

Role até localizar a seção Segurança (Security) e na sequencia clique em Abrir Mesmo Assim (Open Anyway)

Confirme, cliquando em Abrir Mesmo Assim (Open Anyway)

Clique em Use sua Senha (Use Password)

Digite o usuário e senha de um usuário com autorização de Administrador do equipamento

Clique no botão OK para autorizar a execução do WebAgent

Registrando o certificado SSL para uso do WebAgent (topo)

Para utilizar o Websocket Secure (wss) é necessário registrar o TOTVS Certificate em seu sistema operacional.

 Para usuários Windows (automático) (topo)

O registro é automático para Windows 10/11, 32 ou 64 bits, e será efetivado na primeira execução do WebAgent.

Para usuários Linux (automático a partir da versão 1.0.15) (topo)

    Ubuntu    

• Após a instalação o WebAgent
• Localize o arquivo totvs_certificate_CA.crt na pasta /opt/web-agent

• Acesse seu navegador e efetue o registro:
  

  Para o Google Chrome

  ---

  • Na barra de navegação digite: chrome://settings/certificates
  • Acesse: Authorities (autoridades)
  • Na sequência: Import (importar)
  • Selecione o totvs_certificate_CA.crt na pasta /opt/web-agent
  • Selecione todos os Trusts, e por fim, o botão OK
    

  Para o Microsoft Edge

  ---

  • Na barra de navegação digite: edge://settings/privacy/manageCertificates

  • Acesse: Authorities (autoridades)

  • Na sequência: Import (importar)

  • Selecione o totvs_certificate_CA.crt na pasta /opt/web-agent

  • Selecione todos os Trusts e Okay
    

  Para o Firefox

  ---

  • Na barra de navegação digite: about:preferences#privacy

  • Acesse: View Certificates… (verificar certificados)

  • Acesse: Authorities (autoridades)

  • Na sequência: Import (importar)

  • Selecione o totvs_certificate_CA.crt na pasta /opt/web-agent

  • Selecione todos os Trusts e OK
    

        Fedora, Oracle Linux e Red Hat

• Para Google Chrome e Firefox o registro do certificado segue os mesmos passos do Ubuntu.

  Para o Microsoft Edge

  ---

  • O Edge utiliza o certificado do Sistema Operacional, proceda da seguinte forma para o registro:
    
    

    • Copie o certificado da pasta do web-agent para a pasta de certificados

      • sudo cp /opt/web-agent/totvs_certificate_CA.crt /etc/pki/ca-trust/source/anchors/
        
        

    • Registre o certificado

      • sudo update-ca-trust
        
        

    • Verifique se o certificado foi instalado

      • trust list | grep TO    
        label: TOTVS certificate CA

• Acesse os links abaixo para mais informações:
  • https://docs.fedoraproject.org/en-US/quick-docs/using-shared-system-certificates/
  • https://www.redhat.com/sysadmin/ca-certificates-cli

Para usuários macOS (topo)

Este exemplo de registro do certificado se baseia no macOS Sequoia.  (💡 Dica: Clique nas imagens para melhor visualização )

Após instalar o WebAgent, localize o arquivo totvs_certificate_CA.crt na pasta /Applications/web-agent.app/Contents/MacOS

No App Acesso às Chaves (Keychain Access) , selecione Sistema (System), e na sequência Certificados (Certificates).

Arraste o arquivo do certificado para o App Acesso às Chaves (Keychain Access).

Configure a confiança do certificado, clicando com o botão direito do mouse sobre o arquivo, e escolhendo a opção Obter Informações (Get Info).

Expanda a opção Confiança (Trust), e coloque Confiar Sempre (Always Trust) para todas as opções disponíveis.

Ao confirmar as informações, se for solicitado usuário e senha, utilize um usuário com acesso de administrador.

Habilitando o WebAgent na Tela de Parâmetros (topo)

Para habilitar o uso do WebAgent pelo WebApp, na Tela de Parâmetros, selecione o botão de configuração.

Escolha a porta de inicialização do WebAgent (por padrão é a 21021).

Na sequencia feche essa janela clicando no X na parte superior da janela de configuração.

Ao confirmar os dados na Tela de Parâmetros será exibida a mensagem abaixo, solicitando autorização para abertura do WebAgent, basta clicar no botão Abrir.

Caso a conexão com o WebAgent falhe ou a solicitação de autorização seja ignorada, será exibida a mensagem de erro a seguir:

Executando o WebAgent em linha de comando (topo)

O WebAgent pode ser iniciado via linha de comando, os parâmetros podem ser usados em conjunto, as opções são:

web-agent -c --port 21023

web-agent -v
v1.0.9-RC3 - x64

Comando launch: Abrindo o navegador diretamente pelo WebAgent (topo)

Vídeo com detalhes do processo:

Permite abrir uma janela destacada do navegador a partir do WebAgent.

web-agent launch...

webagent launch "ip+porta+[parâmetros<opcional>]" --browser="caminho para o navegador"

Exemplos:

Nos exemplos abaixo será aberto o SIGAFAT e preenchidos os parâmetros de abertura (&A=), artificio utilizado em produtos como SIGALOJA, e útil em algumas customizações.

C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011/webapp/?E=padrao&P=SIGAFAT&A=param1&A=param2&A=param3" --browser="C:\Program Files\Google\Chrome\Application\chrome.exe"

/opt/web-agent/web-agent launch "http://10.173.9.215:5011/webapp/?E=padrao&P=SIGAFAT&A=param1&A=param2&A=param3" --browser="/usr/bin/microsoft-edge"

Lista de parâmetros disponíveis:

Comando --headless: Executando aplicações sem interface através do WebAgent (topo)

Vídeo com detalhes do processo:

A partir da versão 1.0.9 do WebAgent será possível executar programas sem interface gráfica, com o objetivo de dinamizar automações, testes e etc.

Nesse modo é recomendado o uso dos navegadores Google Chrome, Microsoft Edge ou Mozilla Firefox. 

webagent launch "ip+porta+[parâmetros<opcional>]" --browser="caminho para o navegador" --headless

Exemplos:

O exemplo abaixo executa a função de usuário u_headless em um navegador sem interface gráfica.

C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011/webapp/?E=padrao&P=u_headless" --browser="C:\Program Files\Google\Chrome\Application\chrome.exe" --headless

/opt/web-agent/web-agent launch "http://10.173.9.215:5011/webapp/?E=padrao&P=u_headless" --browser="/usr/bin/microsoft-edge" --headless

/Applications/web-agent.app/Contents/MacOS/web-agent launch "http://10.173.9.215:5011/webapp/?E=padrao&P=u_headless" --browser="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless

{
"policies": {
"Certificates": {
    "ImportEnterpriseRoots": true,
    "Install" [
               "/opt/web-agent/totvs_certificate_CA.crt"
               ]
         }
    }
}

Comando --kiosk: Executando o ERP em tela cheia (fullscreen) (topo)

O parâmetro --kiosk permite iniciar o ERP em tela cheia.
O parâmetro --kiosk é padrão em todos os navegadores homologados para o WebApp, menos o Safari, por este motivo propagamos sua chamada através do WebAgent para facilitar a operação de nossos usuários.

webagent launch "ip+porta+[parâmetros<opcional>]" --kiosk --browser="caminho para o navegador"

Exemplos:

O exemplo abaixo executa a função de usuário u_myapp em um navegador em tela cheia.

C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011/webapp/?E=padrao&P=u_myapp" --kiosk --browser="C:\Program Files\Google\Chrome\Application\chrome.exe"

/opt/web-agent/web-agent launch "http://10.173.9.215:5011/webapp/?E=padrao&P=u_myapp" --kiosk --browser="/usr/bin/microsoft-edge"

Entendendo as arquiteturas 32 e 64 bits para uso do WebAgent (topo)

Video sobre o tema

O WebAgent para Linux e macOS será distribuido somente na versão 64 bits.

Para Windows ele será distribuido também na versão 32 bits, devido a dois cenários:

Mais alguns detalhes sobre arquitetura clique aqui.

Exemplos de integração utilizando o WebAgent (topo)

Integração com o Microsoft Excel, mais informações aqui.  (💡 Dica: Clique nas imagens para melhor visualização )

Consumindo uma DLL através da função ExeDllRun3:

Executando uma aplicação nativa através da função ShellExecute:

Retornando as pastas e arquivos de um diretório através da função Directory:

Recuperando a configuração da estação de trabalho através do Shift+F6.

Sistemas Operacionais homologados (topo)

O WebAgent está disponível e homologado para os seguintes Sistemas Operacionais:

Sistemas Operacionais em homologação (topo)