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 você ainda não gerou seu CSR, a primeira seção mostra como fazê-lo.

Também gravamos um vídeo que o guia por todo o processo. Você pode assistir ao vídeo, ler as instruções, ou fazer as duas coisas. Você pode assistir ao vídeo abaixo.

Gerar um código CSR para o Tomcat

CSR significa Certificate Signing Request (Solicitação de Assinatura de Certificado), um bloco de texto que contém informações atuais sobre seu domínio e organização. Todo comprador de um certificado SSL comercial deve enviar um CSR à Autoridade Certificadora (o provedor SSL) para passar pela validação e receber o certificado. Se o CSR contiver informações incorretas, a CA não o assinará.

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

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

Importante: mantenha um registro do arquivo keystore e do alias que você usou ao gerar o CSR. Você importará seu certificado assinado de volta para esse mesmo alias mais tarde, pois é onde reside a chave privada correspondente.

Depois que a Autoridade Certificadora validar sua solicitação e enviar os arquivos SSL, continue com a instalação abaixo.

Instalar um certificado SSL no Tomcat

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

Etapa 1: Prepare seus arquivos de certificado SSL

Sua Autoridade Certificadora envia os arquivos por e-mail para o endereço que você forneceu, geralmente como um arquivo ZIP. Extraia-o. Dependendo da CA, os arquivos chegam em um dos dois formatos:

• PKCS#7: um único arquivo .p7b (ou .cer) que já reúne seu certificado junto com os certificados raiz e intermediários.
• PEM: arquivos separados, tipicamente um .crt para seu certificado de servidor, além de arquivos individuais root.crt e intermediate.crt.

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

Etapa 2: Importe o certificado para seu keystore

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

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

Substitua ssldragon pelo seu próprio alias e example pelos nomes dos seus arquivos. O alias deve ser aquele que já contém sua chave privada (o alias da etapa do CSR). Quando você 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 maior que 1. Isso confirma que o certificado assinado agora está anexado à sua chave privada.

Formato PEM. Importe os certificados separadamente, na ordem da cadeia: primeiro o raiz, depois quaisquer intermediários, e por último o certificado do seu domínio. Importar a cadeia primeiro permite que o keytool construa 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 sua CA fornecer vários certificados intermediários, importe cada um sob seu próprio alias confiável, seguindo a ordem em que assinam uns aos outros (do raiz até o certificado do seu domínio). Por exemplo, um certificado Sectigo PositiveSSL vem com mais de um intermediário, então importe-os em sequência antes do certificado do domínio.

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

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

Aqui, ssldragon deve ser o seu alias existente de chave privada. Como esse alias já tem uma chave, o keytool trata essa importação como uma resposta de certificado e vincula o certificado assinado à chave. Esta é a etapa 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 confiável autônoma sem chave anexada, e o TLS falhará. Se não tiver certeza de qual alias contém sua chave, execute keytool -list -v -keystore example.jks e use o alias cujo tipo seja PrivateKeyEntry.

Etapa 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 arquivo em um 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 referencia 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 arquivo do seu 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 sua chave privada e certificado assinado (aqui, ssldragon). Isso informa ao Tomcat qual entrada usar quando o keystore contém mais de uma.

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

Forma legada (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 ser usada nas versões suportadas do Tomcat.

Etapa 4: Salve o server.xml e reinicie o Tomcat

Salve o server.xml, depois reinicie o Tomcat para que ele 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 sendo executado como um serviço, reinicie-o através do seu gerenciador de serviços (por exemplo systemctl restart tomcat no Linux, ou o painel de Serviços no Windows). Parabéns, seu certificado SSL agora está instalado no seu servidor Tomcat.

Teste sua instalação SSL no Tomcat

Depois de instalar o certificado, pequenos erros podem passar despercebidos e afetar como os navegadores tratam seu site. Faça da verificação da instalação um hábito. Execute nosso SSL Checker para uma varredura instantânea que revela problemas como um certificado intermediário ausente ou uma cadeia não confiável.

Perguntas Frequentes