Certificate Management Service:Install an SSL certificate on a JBoss server (Linux)

Step 1: Download the SSL certificate

1. On the SSL Certificates page, find the certificate you want to deploy and confirm the following information:

   1. Certificate Status: Make sure that the status is Issued. If the status is About to Expire or Expired, you must renew the SSL certificate.

   2. Bound Domains: Make sure that the certificate covers all domain names that you want to protect. Otherwise, browsers show security warnings when users access unmatched domain names over HTTPS. To add or modify domain names, see Add and replace domain names.

      Verifying the domain name match

      The Bound Domains of a certificate can include multiple exact and wildcard domain names. The matching rules are as follows:

      • Exact domain name: An exact domain name certificate applies only to the specified domain name.

        • A certificate for example.com applies only to example.com.

        • A certificate for www.example.com applies only to www.example.com.

      • Wildcard domain name: A wildcard domain name certificate applies only to first-level subdomains.

        • A certificate for *.example.com applies to first-level subdomains such as www.example.com and a.example.com.

        • A certificate for *.example.com does not apply to the root domain example.com or multi-level subdomains such as a.b.example.com.

      Note

      To match a multi-level subdomain, the Bound Domains field must include the specific domain name (for example, a.b.example.com) or a corresponding wildcard domain name (for example, *.b.example.com).

2. Locate the target certificate. In the Actions column, click More. On the Download tab, set Server Type to JKS and download the files.

3. The extracted files include a keystore file (.jks) and a password file (jks-password.txt). The keystore contains the private key and complete certificate chain for deployment.

   Note

   JKS (Java KeyStore) is the standard keystore format for Java environments.

Step 2: Install the SSL certificate on the JBoss server

1. Log on to the Linux server.

   Alibaba Cloud server

   The following operations use an Alibaba Cloud ECS instance as an example. For other types of servers, see their respective documentation.

   1. Log on to the ECS console. In the top navigation bar, select the region where the target ECS instance is located.

   2. In the left-side navigation pane, choose Instances & Images > Instances. On the Instances page, find the target ECS instance and click Remote Connection in the Remote connection column.

   3. In the dialog box that appears, select Workbench and click Sign in now.

   4. Select Terminal Connection as the connection method, enter the authentication information, and follow the on-screen instructions to complete the logon. You can then access the server terminal. For more information, see Connect to an ECS instance by using Workbench.

      Note

      If the Security Group Whitelist Opening Prompt panel appears, click Add Rule as prompted.

   Other cloud providers

   Use the remote connection feature provided by the cloud provider to log on to the server terminal.

   On-premises servers

   Use an SSH tool on your local machine to log on to the server terminal.

   • Windows: Run the ssh <username>@<server_ip_address> command in Command Prompt (cmd) or PowerShell. If the ssh command is not supported, you can use a third-party tool, such as PuTTY or WinSCP, to establish a connection.

   • macOS/Linux: Run the ssh <username>@<server_ip_address> command in the built-in terminal.

   Some of the following commands vary based on the operating system. Select the appropriate command for your server's OS.

   • RHEL/CentOS series: includes Alibaba Cloud Linux, Red Hat Enterprise Linux, CentOS, AlmaLinux, Rocky Linux, Anolis OS, and their derivatives.

   • Debian/Ubuntu series: includes Debian, Ubuntu, and their derivatives.

   How to identify your operating system series

   Run the cat /etc/os-release command in the server terminal and check the ID_LIKE and ID fields in the output.

   • If the value of ID_LIKE or ID contains rhel or centos, the operating system belongs to the RHEL/CentOS series.

   • If the value of ID_LIKE or ID contains debian or ubuntu, the operating system belongs to the Debian/Ubuntu series.

2. Open port 443 in the security group and firewall.

   1. Run the following command in the server terminal to check whether port 443 is open:

      RHEL/CentOS

      command -v nc > /dev/null 2>&1 || sudo yum install -y nc
      # Replace <your_server_public_ip_address> with the public IP address of your server.
      sudo ss -tlnp | grep -q ':443 ' || sudo nc -l 443 & sleep 1; nc -w 3 -vz <your_server_public_ip_address> 443

      If the output contains Ncat: Connected to <your_server_public_ip_address>:443, port 443 is open. Otherwise, you must open port 443 in the security group and firewall.

      Debian/Ubuntu

      command -v nc > /dev/null 2>&1 || sudo apt-get install -y netcat
      # Replace <your_server_public_ip_address> with the public IP address of your server.
      sudo ss -tlnp | grep -q ':443 ' || sudo nc -l -p 443 & sleep 1; nc -w 3 -vz <your_server_public_ip_address> 443

      If the output contains Connection to <your_server_public_ip_address> port [tcp/https] succeeded! or [<your_server_public_ip_address>] 443 (https) open, port 443 is open. Otherwise, you must open port 443 in the security group and firewall.

   2. Open port 443 in the security group.

      Important

      If your server is deployed on a cloud platform, make sure that its security group allows inbound traffic on TCP port 443. Otherwise, the service is not accessible from the internet. The following operations use an Alibaba Cloud ECS instance as an example. For other cloud platforms, see their official documentation.

      Go to the ECS Instances page and click the name of the target instance to go to its details page. For more information, see Add a security group rule. Add a rule to the security group with Action set to Allow, Protocol Type set to TCP, Port Range set to HTTPS(443), and Authorization Object set to Anywhere (0.0.0.0/0).

   3. Open port 443 in the firewall.

      Run the following command to identify the current firewall service on your system:

      if command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet firewalld; then
          echo "firewalld"
      elif command -v ufw >/dev/null 2>&1 && sudo ufw status | grep -qw active; then
          echo "ufw"
      elif command -v nft >/dev/null 2>&1 && sudo nft list ruleset 2>/dev/null | grep -q 'table'; then
          echo "nftables"
      elif command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet iptables; then
          echo "iptables"
      elif command -v iptables >/dev/null 2>&1 && sudo iptables -L 2>/dev/null | grep -qE 'REJECT|DROP|ACCEPT'; then
          echo "iptables"
      else
          echo "none"
      fi

      If the output is none, no further action is required. Otherwise, based on the firewall type (firewalld, ufw, nftables, or iptables), run the corresponding command to open port 443:

      firewalld

      sudo firewall-cmd --permanent --add-port=443/tcp && sudo firewall-cmd --reload

      ufw

      sudo ufw allow 443/tcp

      nftables

      sudo nft add table inet filter 2>/dev/null
      sudo nft add chain inet filter input '{ type filter hook input priority 0; }' 2>/dev/null
      sudo nft add rule inet filter input tcp dport 443 counter accept 2>/dev/null

      iptables

      sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

      To prevent iptables rules from being lost after a system reboot, run the following command to make the rules persistent:

      RHEL/CentOS

      sudo yum install -y iptables-services
      sudo service iptables save

      Debian/Ubuntu

      sudo apt-get install -y iptables-persistent
      sudo iptables-save | sudo tee /etc/iptables/rules.v4 >/dev/null

3. Create a cert directory under the JBoss standalone/configuration directory for the keystore file.

   mkdir cert # Create a certificate directory named cert.  

4. Upload the keystore file to the cert directory.

   Note

   Use a remote logon tool such as PuTTY, Xshell, or WinSCP to upload the file.

   If you use an Alibaba Cloud Elastic Compute Service (ECS) instance, see Transfer files to a Windows instance using Remote Desktop or Windows APP or Upload a file to a Linux instance.

5. Open standalone.xml, locate the HTTPS connector (<connector name="https">) in <subsystem xmlns="urn:jboss:domain:web:1.1">, and update it as follows:

   <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
       <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
       <!--
           Configure the certificate password and path.
           Set password to the certificate password from jks-password.txt.
           Set certificate-key-file to the actual path where the certificate is stored.
       -->
       <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
           <ssl name="https" password="******" certificate-key-file="../standalone/configuration/cert/domain_name.jks"/>
       </connector>
   </subsystem>
   
   <!--Configure remote access to JBoss and the HTTPS port-->
   <interfaces>
       <interface name="management">
           <inet-address value="${jboss.bind.address.management:127.0.0.1}"></inet>
       </interface>
       <!--Enable remote access-->
       <interface name="public">
           <inet-address value="${jboss.bind.address:0.0.0.0}"></inet>
       </interface>
       <interface name="unsecure">
           <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"></inet>
       </interface>
   </interfaces>
   <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
       <socket-binding name="management-native" interface="management" port="${jboss.management.native.port:9999}"></socket>
       <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"></socket>
       <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9443}"></socket>
       <socket-binding name="ajp" port="8009"></socket>
       <!--Change the HTTP port to 80-->
       <socket-binding name="http" port="80"></socket>
       <!--Change the HTTPS port to 443-->
       <socket-binding name="https" port="443"></socket>
       <socket-binding name="osgi-http" interface="management" port="8090"></socket>
       <socket-binding name="remoting" port="4447"></socket>
       <socket-binding name="txn-recovery-environment" port="4712"></socket>
       <socket-binding name="txn-status-manager" port="4713"></socket>
       <outbound-socket-binding name="mail-smtp">
           <remote-destination host="localhost" port="25"></remote>
       </outbound-socket-binding>
   </socket-binding-group>

6. Go to the JBoss bin directory and run the following command to restart the server.

   sh standalone.sh

Step 3: Verify the installation

Certificate not working or HTTPS inaccessible

Common causes:

• Port 443 is not open in the server's security group or firewall. Open port 443 in the security group and firewall.

• The Bound Domains of the certificate does not include the accessed domain name. Check whether the certificate matches the target domain names.

• The JBoss service was not restarted after the configuration change. Restart the JBoss server.

• The keystore file was not replaced correctly, or the certificate path in the JBoss configuration is wrong. Verify that the configuration file and keystore file are up to date and valid.

• The domain name is integrated with cloud services such as CDN, SLB, or WAF, but the certificate is not installed on the corresponding service. For more information, see Certificate deployment location when traffic passes through multiple cloud services.

• The domain name resolves to multiple servers, but the certificate is installed on only some of them. You must install the certificate on each server.

How do I update an SSL certificate on JBoss?

Back up the original keystore file (.jks) and password file (.txt) on the server. Download the new files from the Certificate Management Service console and upload them to the same path with the same filenames. Restart JBoss for the new certificate to take effect.