如何在JBoss Server上安装SSL证书

本教程将向您展示如何使用 keytool 和 Elytron 安全子系统在 JBoss EAP 和 WildFly 上安装 SSL 证书。如果您还没有证书文件，第一部分将介绍如何生成 CSR。

版本说明：现代版本的 JBoss EAP（7.1 及更高版本，包括 EAP 8）以及近期的 WildFly 版本都是通过 elytron 子系统配置 HTTPS，并将其连接到 Undertow 的 https-listener。旧的 security-realm 方式以及传统的 Tomcat 或 Jetty 连接器已被弃用，因此本指南采用当前的方法。

我们还录制了一段视频，带您完整了解整个过程。您可以观看视频、阅读说明，或者两者结合。您可以在下方观看视频。

在 JBoss 上生成 CSR 代码

CSR（证书签名请求）是一段编码文本，您在订购证书时将其发送给证书颁发机构（CA）。它包含您的域名和组织信息，CA 会用它来验证您的请求。生成 CSR 的同时也会创建与之匹配的私钥，该私钥保留在您的服务器上，并在安装过程中需要用到。

您有两种选择：

• 使用我们的CSR 生成器自动创建 CSR。
• 参照我们的在 JBoss 上生成 CSR 的分步教程操作。

在 JBoss 上，CSR 是使用 keytool 从 .jks 或 .p12 密钥库生成的。请记下您现在选择的别名（alias）和密钥库（keystore）名称：稍后您需要将签发的证书导入到完全相同的这个别名中。在订购时将 CSR 提交给 CA，证书签发后，请继续进行下面的安装步骤。

在 JBoss 服务器上安装 SSL 证书

第 1 步：准备证书文件

验证通过后，CA 会通过电子邮件发送您的证书文件，通常是一个 ZIP 压缩包。解压它。您应该会得到：

• 您的主证书（.crt、.cer 或 .pem 文件）。
• 中间证书，通常以 .ca-bundle 文件形式提供（即CA 证书链文件）。有些 CA 也会包含根证书。
• 您在生成 CSR 时创建的密钥库（.jks 或 .p12），其中包含存放在生成 CSR 时所选别名下的私钥。

请将这些文件保存在一起，并复制到服务器上，例如复制到 JBoss 配置目录（$JBOSS_HOME/standalone/configuration/）中。如果某个文件以文本形式打开，您可以确认它包含预期的 BEGIN CERTIFICATE 和 END CERTIFICATE 行。

第 2 步：将 CA 证书链导入密钥库

先导入中间证书（以及根证书，如有提供），以便 keytool 能够构建完整的信任链。使用存放您私钥的同一个密钥库，并为每个 CA 证书分配各自的别名：

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

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

如果您的 CA 提供的是单个 .ca-bundle 文件，请将其导入到一个别名下（例如 -alias intermediate）。系统提示时，输入密钥库密码并确认信任。这些是受信任证书条目，而非密钥条目，因此不会影响您的私钥。

第 3 步：将已签发的证书导入到您的密钥别名中

现在将您已签发的证书（CA 返回的回复）导入到生成 CSR 时使用的确切别名中。由于该别名已经保存了私钥，keytool 会将此操作视为证书回复，并用 CA 签发的证书链替换临时的自签名证书，同时保持私钥完好无损：

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

将 your_csr_alias 替换为您生成 CSR 时使用的别名，将 your_keystore.jks 替换为您的密钥库。成功后 keytool 会输出 Certificate reply was installed in keystore。

重要提示：不要在此处创建新的别名。将回复导入到新别名下会创建一个没有私钥的受信任证书条目，证书链会丢失，服务器也无法完成 TLS 握手。如果您看到 Failed to establish chain from reply，说明第 2 步中的中间证书或根证书未导入密钥库。

您可以验证结果，此时该别名应显示长度大于 1 的证书链：

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

第 4 步：在 Elytron 子系统中配置 HTTPS

将密钥库放置在 $JBOSS_HOME/standalone/configuration/ 中，然后定义一个 Elytron 的 key-store、key-manager 和 server-ssl-context。最快的方式是使用管理 CLI。启动服务器，使用 jboss-cli.sh --connect 连接，并运行批处理以使更改一并生效：

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

接下来，将 Undertow 的 https-listener 指向新的 ssl-context。Undertow 不能同时引用旧版 security-realm 和 Elytron ssl-context，因此请在一个批处理中同时移除旧引用并设置新引用：

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

如果您更喜欢直接编辑 standalone.xml（在服务器停止的情况下），等效的配置在 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>

而 undertow 子系统中对应的监听器则引用该 ssl-context：

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

将 protocols 限制为 TLS 1.3 和 TLS 1.2，可禁用已过时的 TLS 1.0 和 1.1。默认的 HTTPS 端口是 8443；如果您需要使用标准端口，可以通过负载均衡器或端口重定向将其映射到 443。

第 5 步：重启 JBoss

如果您是手动编辑了 standalone.xml，请重启服务器以加载新配置。如果您使用的是上面的 CLI 批处理，更改会立即生效，但重新加载可以确认启动过程无误：

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

启动过程中请留意服务器日志，检查是否有 SSL 或 Elytron 相关的错误。启动顺利后，您的 SSL 证书就已成功安装在 JBoss 上了。

测试您的 SSL 安装

安装完成后，请确认证书和证书链已正确提供。通过 HTTPS 打开您的网站（例如 https://www.yourdomain.com:8443）并检查锁形图标，或使用我们的SSL 检测工具进行外部扫描，获取有关证书、证书链和协议支持情况的完整报告。您也可以通过命令行进行检查：

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

此命令会打印出 JBoss 提供的证书的签发机构和有效期。如果签发机构是您的 CA（而不是自签名条目），说明证书回复已正确导入。

常见问题解答