Em Desenvolvimento
Esta documentação ainda está em desenvolvimento. Agradecemos sua paciência!
Pular para o conteúdo principal
Versão: 03.008.000 🚧 (em desenvolvimento)

Parametrizando certificado SSL

aviso

Alterar qualquer valor no docker-compose se faz necessário reiniciar os serviços.

O HTF Apps suporta três formas de habilitar HTTPS no serviço proxy. Após configurar o certificado, é necessário também atualizar o alfresco-global.properties para refletir o protocolo HTTPS.


Opção 1 — Certificado auto assinado HTF (recomendado para redes internas)​

O proxy gera automaticamente um certificado assinado pelo HTF Root CA. Os certificados gerados são reconhecidos como seguros pelos aplicativos HTF Apps. Em estações Windows, Linux e Mac, é necessário importar o certificado raiz manualmente.

No serviço proxy do docker-compose:

proxy:
environment:
- PROTOCOL=https
- AUTO_SELFSIGN=on
- AUTO_SELFSIGN_HOSTS=DNS:meudominio.intranet

Substitua meudominio.intranet pelo nome de domínio ou hostname configurado para o servidor.

Importando o certificado raiz nas estações de trabalho:

O arquivo HTF Root.cer está incluído no pacote de instalação. Importe-o como certificado raiz confiável:

  • Windows: clique duplo no arquivo → Instalar certificado → Repositório: Autoridades de Certificação Raiz Confiáveis.
  • Linux: copie para /usr/local/share/ca-certificates/ e execute update-ca-certificates.
  • macOS: abra o Keychain Access, importe e marque como "Sempre confiar".

Opção 2 — Certificado de uma CA válida (recomendado para acesso externo)​

Substitua os arquivos de certificado dentro do container pelo certificado emitido por uma CA reconhecida:

ArquivoConteúdo
/config/fullchain.pemCertificado em cadeia (cert + intermediários)
/config/privkey.pemChave privada do certificado

No serviço proxy do docker-compose, defina:

proxy:
environment:
- PROTOCOL=https

Opção 3 — LetsEncrypt (descontinuado)​

aviso

Esta opção está sendo descontinuada. Dispositivos de captura atuais não reconhecem certificados LetsEncrypt como válidos. Use apenas para acesso via navegadores em Windows, Linux e Mac.

proxy:
environment:
- PROTOCOL=https
- AUTO_LETSENCRYPT=on
- AUTO_SELFSIGN_HOSTS=DNS:meudominio.com

Atualizando a URL pública (arquivo .env)​

Após configurar o certificado, atualize a PUBLIC_BASE_URL no .env para usar HTTPS:

PUBLIC_BASE_URL=https://meudominio.intranet:8443

Ajuste meudominio.intranet e a porta (8443 ou 8080) conforme o proxy. A PUBLIC_BASE_URL define o protocolo, o host e a porta públicos — e cobre também o CMIS e o AOS (não é preciso editá-los separadamente).


Confiar em uma CA nova nos serviços (sem rebuild)​

O proxy cuida do certificado que o servidor apresenta. Esta seção trata do inverso: o certificado dos serviços externos que a instalação acessa (carimbo do tempo da assinatura, Gemini, DocuSign, backoffice de licenciamento, destinos de backup em nuvem, etc.). Quando um desses serviços passa a usar uma autoridade certificadora (CA) raiz que o conjunto de CAs da imagem ainda não conhece, a conexão falha com erros como PKIX path building failed ou unable to get local issuer certificate — por exemplo, a assinatura com carimbo do tempo do SERPRO que passa a encadear na GlobalSign Root R46.

As imagens já trazem um conjunto atualizado de CAs públicas. Para incluir uma CA adicional sem reconstruir a imagem:

  1. Obtenha a CA raiz (ou intermediária) em formato PEM (.crt ou .pem) no repositório oficial da autoridade certificadora.

  2. Confira o arquivo antes de usar:

    openssl x509 -in arquivo.crt -noout -subject -issuer
  3. Copie o arquivo para a pasta extra-cacerts/, ao lado do docker-compose.yml.

  4. Reinicie o serviço que falha (por exemplo, docker compose restart tools).

No início de cada serviço, os arquivos da pasta são importados no conjunto de CAs de confiança do sistema e do Java, de forma idempotente. Se houver erro na importação, ele é apenas registrado em log e o serviço sobe normalmente. A pasta é compartilhada pelos serviços do toolkit (como tools, signverification, licensing, iagemini, process, captureconnector, alfresco e share), pelo Portal e pelo Backup Agent.

Atualizar o conjunto de CAs a cada subida​

No .env, a variável CA_REFRESH_ON_BOOT (padrão false) controla se o conjunto de CAs de confiança do sistema é atualizado a cada inicialização do serviço. A atualização é feita em regime de melhor esforço: se não for possível, o serviço sobe normalmente.

CA_REFRESH_ON_BOOT=true
aviso

Importe apenas CAs legítimas, obtidas de fonte oficial: confiar em uma CA significa confiar em tudo o que ela emitir. Se a rede usa inspeção TLS (proxy corporativo), a CA a importar é a do proxy.