Como Instalar um Certificado SSL no Servidor JBoss

Este tutorial mostra como instalar um certificado SSL no JBoss EAP e WildFly usando o keytool e o subsistema de segurança Elytron. Se você ainda não tem os arquivos do certificado, a primeira secção aborda a geração de um CSR.

Nota sobre versões: o JBoss EAP moderno (7.1 e posteriores, incluindo o EAP 8) e as versões recentes do WildFly configuram o HTTPS através do subsistema elytron ligado ao https-listener do Undertow. O antigo método security-realm e os conectores legados Tomcat ou Jetty estão obsoletos, portanto este guia usa a abordagem atual.

Também gravámos 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 no JBoss

Um CSR (Certificate Signing Request) é um bloco de texto codificado que envia à Autoridade Certificadora (CA) quando encomenda um certificado. Ele contém os dados do seu domínio e da sua organização, que a CA usa para validar o pedido. Gerar o CSR também cria a chave privada correspondente, que fica no seu servidor e é necessária 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 JBoss.

No JBoss, o CSR é gerado com o keytool a partir de um repositório de chaves .jks ou .p12. Anote o alias e o nome do keystore que escolher agora: mais tarde terá de importar o certificado assinado de volta para esse mesmo alias. Envie o CSR à CA durante a sua encomenda e, assim que o certificado for emitido, continue com a instalação abaixo.

Instalar um certificado SSL no servidor JBoss

Passo 1: Prepare os arquivos do seu certificado

Após a validação, a CA envia por e-mail os arquivos do seu certificado, normalmente num arquivo ZIP. Extraia-o. Deve ter:

• O seu certificado primário (um arquivo .crt, .cer ou .pem).
• Os certificados intermediários, frequentemente entregues num arquivo .ca-bundle (o pacote CA). Algumas CAs incluem também o certificado raiz.
• O keystore (.jks ou .p12) que criou com o CSR, que contém a sua chave privada sob o alias que escolheu ao gerar o CSR.

Mantenha estes arquivos juntos e copie-os para o servidor, por exemplo para o diretório de configuração do JBoss ($JBOSS_HOME/standalone/configuration/). Se um arquivo abrir como texto, pode confirmar que contém as linhas esperadas BEGIN CERTIFICATE e END CERTIFICATE.

Passo 2: Importe a cadeia da CA para o keystore

Importe primeiro os certificados intermediários (e o raiz, se fornecido) para que o keytool possa construir uma cadeia de confiança completa. Use o mesmo keystore que contém a sua chave privada e atribua a cada certificado da CA o seu próprio alias:

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

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

Se a sua CA enviou um único arquivo .ca-bundle, importe-o com um único alias (por exemplo -alias intermediate). Quando solicitado, introduza a palavra-passe do keystore e confirme a confiança. Estas entradas são entradas de certificado confiável, não entradas de chave, pelo que não afetam a sua chave privada.

Passo 3: Importe o certificado assinado para o seu alias de chave

Agora importe o seu certificado assinado (a resposta da CA) para o alias exato que usou ao gerar o CSR. Como esse alias já contém a chave privada, o keytool trata isto como uma resposta de certificado e substitui o certificado autoassinado temporário pela cadeia assinada pela CA, mantendo a chave intacta:

keytool -import -trustcacerts -alias your_csr_alias -file your_domain.crt -keystore your_keystore.jks

Substitua your_csr_alias pelo alias que usou ao gerar o CSR e your_keystore.jks pelo seu keystore. Em caso de sucesso, o keytool imprime Certificate reply was installed in keystore.

Importante: não invente um novo alias aqui. Importar a resposta sob um novo alias cria uma entrada de certificado confiável sem chave privada, a cadeia é perdida e o servidor não consegue concluir o handshake TLS. Se vir Failed to establish chain from reply, significa que o intermediário ou o raiz do Passo 2 está em falta no keystore.

Pode verificar o resultado; o alias deve agora mostrar uma cadeia de certificados com comprimento superior a 1:

keytool -list -v -alias your_csr_alias -keystore your_keystore.jks

Passo 4: Configure o HTTPS no subsistema Elytron

Coloque o keystore em $JBOSS_HOME/standalone/configuration/ e, em seguida, defina um key-store, key-manager e server-ssl-context do Elytron. A forma mais rápida é através da CLI de gestão. Inicie o servidor, conecte-se com jboss-cli.sh --connect e execute um lote para que as alterações se apliquem em conjunto:

batch

/subsystem=elytron/key-store=httpsKS:add(path=your_keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=your_keystore_password}, type=JKS)

/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS, credential-reference={clear-text=your_keystore_password})

/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM, protocols=["TLSv1.3","TLSv1.2"])

run-batch

De seguida, aponte o https-listener do Undertow para o novo ssl-context. O Undertow não pode referenciar simultaneamente um security-realm legado e um ssl-context do Elytron, portanto remova a referência antiga e defina a nova num único lote:

batch

/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=httpsSSC)

run-batch

Se preferir editar diretamente o standalone.xml (com o servidor parado), a configuração equivalente é a seguinte dentro do subsistema elytron:

<tls>
    <key-stores>
        <key-store name="httpsKS">
            <credential-reference clear-text="your_keystore_password"/>
            <implementation type="JKS"/>
            <file path="your_keystore.jks" relative-to="jboss.server.config.dir"/>
        </key-store>
    </key-stores>
    <key-managers>
        <key-manager name="httpsKM" key-store="httpsKS">
            <credential-reference clear-text="your_keystore_password"/>
        </key-manager>
    </key-managers>
    <server-ssl-contexts>
        <server-ssl-context name="httpsSSC" key-manager="httpsKM" protocols="TLSv1.3 TLSv1.2"/>
    </server-ssl-contexts>
</tls>

E o listener correspondente no subsistema undertow referencia esse ssl-context:

<https-listener name="https" socket-binding="https" ssl-context="httpsSSC" enable-http2="true"/>

Limitar os protocols a TLS 1.3 e TLS 1.2 desativa os obsoletos TLS 1.0 e 1.1. A porta HTTPS predefinida é a 8443; mapeie-a para a 443 com um balanceador de carga ou um redirecionamento de porta se precisar da porta padrão.

Passo 5: Reinicie o JBoss

Se editou o standalone.xml manualmente, reinicie o servidor para que carregue a nova configuração. Se usou os lotes de CLI acima, as alterações aplicam-se imediatamente, mas um reload confirma um arranque limpo:

jboss-cli.sh --connect --command=:reload

Observe o registo do servidor à procura de erros de SSL ou Elytron durante o arranque. Assim que arrancar sem problemas, o seu certificado SSL está instalado no JBoss.

Teste a sua instalação SSL

Após a instalação, confirme que o certificado e a cadeia são apresentados corretamente. Abra o seu site através de HTTPS (por exemplo https://www.oseudominio.com:8443) e verifique o cadeado, ou execute uma verificação externa com o nosso SSL Checker para obter um relatório completo sobre o certificado, a cadeia e o suporte de protocolos. Também pode verificar através da linha de comandos:

echo | openssl s_client -connect yourdomain.com:8443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -issuer -dates

Isto imprime o emissor e as datas de validade do certificado que o JBoss está a servir. Se o emissor for a sua CA (e não uma entrada autoassinada), a resposta foi importada corretamente.

Perguntas Frequentes