Como instalar um certificado SSL no Tomcat

Neste tutorial, você aprenderá como instalar um certificado SSL no Apache Tomcat usando o utilitário Java keytool, e depois configurar o conector HTTPS no server.xml. Se ainda não gerou o seu CSR, a primeira seção mostra como fazê-lo.

Também gravamos um vídeo que o guia por todo o processo. Pode assistir ao vídeo, ler as instruções, ou fazer ambos. Pode assistir ao vídeo abaixo.

Gerar um código CSR para o Tomcat

CSR significa Certificate Signing Request (Pedido de Assinatura de Certificado), um bloco de texto que contém os detalhes atuais sobre o seu domínio e organização. Todo comprador de um certificado SSL comercial deve submeter um CSR à Autoridade Certificadora (o fornecedor SSL) para passar pela validação e receber o certificado. Se o CSR contiver detalhes incorretos, a CA não o assinará.

No Tomcat, o CSR é criado com o keytool a partir de um keystore Java, e esse mesmo keystore guarda a chave privada que reutilizará durante a instalação. Tem duas opções:

• Usar o nosso Gerador de CSR para criar o CSR automaticamente.
• Seguir o nosso tutorial passo a passo sobre como gerar um CSR no Tomcat.

Importante: mantenha um registo do ficheiro keystore e do alias que usou ao gerar o CSR. Mais tarde, irá importar o seu certificado assinado de volta para esse mesmo alias, pois é ali que está a chave privada correspondente.

Depois de a Autoridade Certificadora validar o seu pedido e enviar-lhe os ficheiros SSL, continue com a instalação abaixo.

Instalar um certificado SSL no Tomcat

Uma instalação no Tomcat tem duas etapas: primeiro importa a cadeia de certificados e o seu certificado assinado para o keystore que já contém a sua chave privada, depois configura o conector HTTPS no server.xml para usar esse keystore.

Passo 1: Prepare os ficheiros do seu certificado SSL

A sua Autoridade Certificadora envia os ficheiros por e-mail para o endereço que forneceu, normalmente como um arquivo ZIP. Extraia-o. Dependendo da CA, os ficheiros chegam num de dois formatos:

• PKCS#7: um único ficheiro .p7b (ou .cer) que já agrupa o seu certificado juntamente com os certificados raiz e intermediário.
• PEM: ficheiros separados, normalmente um .crt para o certificado do seu servidor, além de ficheiros individuais root.crt e intermediate.crt.

Envie os ficheiros extraídos para o servidor, no mesmo diretório do keystore a partir do qual gerou o seu CSR (referido abaixo como example.jks). Identifique o seu formato e siga as instruções correspondentes.

Gerou o CSR noutro local, de modo que a sua chave privada é um ficheiro separado em vez de uma entrada no example.jks? Salte o keytool: converta PEM para PKCS#12 para agrupar o certificado, a cadeia e a chave num único .p12, e depois referencie esse ficheiro no Passo 3 com certificateKeystoreType=”PKCS12″.

Passo 2: Importe o certificado para o seu keystore

Formato PKCS#7. Como um .p7b já contém a cadeia completa, um único comando importa tudo de uma vez, para o seu alias de chave privada existente:

keytool -import -trustcacerts -alias ssldragon -keystore example.jks -file example.p7b

Substitua ssldragon pelo seu próprio alias e example pelos nomes dos seus ficheiros. O alias deve ser aquele que já contém a sua chave privada (o alias do passo do CSR). Quando vir a mensagem Certificate reply was installed in keystore, a importação foi bem-sucedida. Verifique o conteúdo do keystore com:

keytool -list -v -keystore example.jks

Procure uma entrada cujo tipo seja PrivateKeyEntry com um comprimento de cadeia de certificados superior a 1. Isso confirma que o certificado assinado está agora anexado à sua chave privada.

Formato PEM. Importe os certificados separadamente, pela ordem da cadeia: primeiro a raiz, depois quaisquer intermediários, e o certificado do seu domínio por último. Importar a cadeia primeiro permite ao keytool construir um caminho de confiança completo antes de anexar a resposta à sua chave. Importe o certificado raiz:

keytool -import -trustcacerts -alias root -keystore example.jks -file root.crt

Depois importe o certificado intermediário:

keytool -import -trustcacerts -alias intermediate -keystore example.jks -file intermediate.crt

Se a sua CA fornecer vários certificados intermediários, importe cada um sob o seu próprio alias de confiança, seguindo a ordem em que assinam uns aos outros (da raiz até ao certificado do seu domínio). Por exemplo, um certificado Sectigo PositiveSSL vem com mais de um intermediário, portanto importe-os em sequência antes do certificado de domínio.

Por fim, importe o seu certificado principal (o que foi emitido para o seu domínio) para o alias de chave privada existente, o mesmo alias que usou ao gerar o CSR:

keytool -import -trustcacerts -alias ssldragon -keystore example.jks -file example.crt

Aqui, ssldragon deve ser o seu alias de chave privada existente. Como esse alias já tem uma chave, o keytool trata esta importação como uma resposta de certificado e vincula o certificado assinado à chave. É este o passo que faz o HTTPS funcionar.

Armadilha crítica: não importe o certificado assinado sob um alias completamente novo. Se o alias não tiver uma chave privada existente, o keytool armazena o certificado como uma entrada de confiança independente, sem chave anexada, e o TLS falhará. Se não tiver certeza sobre qual alias contém a sua chave, execute keytool -list -v -keystore example.jks e use o alias cujo tipo é PrivateKeyEntry.

Passo 3: Configure o conector HTTPS no server.xml

Com o certificado no seu keystore, aponte o conector HTTPS do Tomcat para ele. O conector é definido no server.xml, localizado na pasta conf da sua instalação do Tomcat (por exemplo $CATALINA_HOME/conf/server.xml). Abra o ficheiro num editor de texto.

Nas versões atuais do Tomcat (9, 10 e 11), a forma recomendada aninha um elemento SSLHostConfig, que por sua vez contém um elemento Certificate que faz referência ao seu keystore. Adicione ou atualize o conector seguro para ficar assim:

<Connector
    port="443"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="150"
    SSLEnabled="true"
    scheme="https"
    secure="true">
  <SSLHostConfig>
    <Certificate
        certificateKeystoreFile="/your_path/example.jks"
        certificateKeystorePassword="your_keystore_password"
        certificateKeystoreType="JKS"
        certificateKeyAlias="ssldragon"
        type="RSA" />
  </SSLHostConfig>
</Connector>

• certificateKeystoreFile: o caminho completo para o seu ficheiro keystore.
• certificateKeystorePassword: a senha do keystore.
• certificateKeystoreType: JKS para um keystore .jks, ou PKCS12 para um keystore .p12 / .pfx.
• certificateKeyAlias: o alias que contém a sua chave privada e o certificado assinado (aqui, ssldragon). Isto indica ao Tomcat qual entrada servir quando o keystore contém mais de uma.

Nota: a porta 443 é a porta HTTPS padrão usada acima; os exemplos próprios do Tomcat usam por padrão a 8443, portanto use aquela que o seu ambiente espera. Se esta for a sua primeira configuração HTTPS, o conector seguro pode estar comentado no server.xml. Remova os marcadores de comentário à volta para que o conector fique ativo, e certifique-se de que nenhum outro conector já está vinculado à mesma porta.

Forma antiga (Tomcat mais antigo). Guias mais antigos colocam os detalhes do keystore diretamente no conector como atributos keystoreFile e keystorePass. Esse estilo foi substituído pelos elementos SSLHostConfig e Certificate mostrados acima, que é a forma a usar nas versões suportadas do Tomcat.

Passo 4: Guarde o server.xml e reinicie o Tomcat

Guarde o server.xml e depois reinicie o Tomcat para que recarregue a configuração. No Linux, use os scripts incluídos:

$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh

Se o Tomcat estiver a ser executado como um serviço, reinicie-o através do seu gestor de serviços (por exemplo systemctl restart tomcat no Linux, ou o painel de Serviços no Windows). Parabéns, o seu certificado SSL está agora instalado no seu servidor Tomcat.

Teste a sua instalação SSL no Tomcat

Depois de instalar o certificado, pequenos erros podem passar despercebidos e afetar a forma como os navegadores tratam o seu site. Habitue-se a verificar a instalação. Execute o nosso SSL Checker para uma verificação instantânea que revela problemas como um certificado intermediário em falta ou uma cadeia não confiável.

Perguntas Frequentes