Certificate Management Service:Install an SSL certificate on a Spring Boot application (Linux)

Usage notes

Before you begin, ensure you meet the following requirements:

Step 1: Prepare the certificate files

1. Go to the SSL Certificate Management page. In the Actions column of the target certificate, click Download Certificate. On the Download tab, download the certificate file for the JKS Server Type.

   Note

   Spring Boot supports both JKS and PKCS12 (.pfx) formats. This topic uses PKCS12 as an example. After you extract the downloaded file, you get a certificate file (for example, domain.p12) and a password file (p12-password.txt).

2. Upload the extracted certificate file (.pfx or .jks) and password file (.txt) to the server. Store them in a secure, external directory, such as /etc/ssl/myapp.

   Important

   Do not place certificate or private key files in the src/main/resources directory. This packages sensitive keys into application deliverables, such as JAR or WAR files, and can easily lead to key leakage.

   You can use the local file upload feature of your remote login tool, such as PuTTY, Xshell, or WinSCP. If you use an Alibaba Cloud Elastic Compute Service (ECS), see Upload or download files.

Step 2: Configure the Spring Boot application

1. Set environment variables running the export command.

   # Get the password from the password file you downloaded earlier.
   export SSL_KEYSTORE_PASSWORD='your_secure_password'
   # If the private key password is different, set it as well.
   export SSL_KEY_PASSWORD='your_key_password'

2. Configure the application.properties or application.yml file as shown in the following examples.

   Note

   This topic uses Spring Boot version 3.4.10 as an example.

   application.properties

   # Listen on port 443
   server.port=443
   
   # --- SSL configuration ---
   # Path to the certificate file. Use the 'file:' prefix to specify an external absolute path.
   server.ssl.key-store=file:/etc/myapp/ssl/keystore.p12
   # Type of the certificate KeyStore.
   server.ssl.key-store-type=PKCS12
   # Certificate alias, which is usually specified when generating the JKS/P12 file.
   server.ssl.key-alias=mycert
   
   # --- Security configuration: Password management ---
   # Read the password from an environment variable to avoid hard-coding it in the configuration file.
   server.ssl.key-store-password=${SSL_KEYSTORE_PASSWORD}
   # If the private key password differs from the keystore password, read it from an environment variable as well.
   server.ssl.key-password=${SSL_KEY_PASSWORD}
   
   # --- Security configuration: TLS protocols and cipher suites ---
   # Enable secure TLS protocol versions.
   server.ssl.enabled-protocols=TLSv1.2,TLSv1.3
   # Configure recommended strong cipher suites.
   server.ssl.ciphers=TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-RSA-AES128-GCM-SHA256
   
   # Enable HTTP/2 to improve performance.
   server.http2.enabled=true

   application.yml

   server:
     port: 443 # Listen on port 443
   
     ssl:
       # --- SSL configuration ---
       # Path to the certificate file. Use the 'file:' prefix to specify an external absolute path.
       key-store: file:/etc/myapp/ssl/keystore.p12
       # Type of the certificate KeyStore.
       key-store-type: PKCS12
       # Certificate alias, which is usually specified when generating the JKS/P12 file.
       key-alias: mycert
   
       # --- Security configuration: Password management ---
       # Read the password from an environment variable to avoid hard-coding it in the configuration file.
       key-store-password: ${SSL_KEYSTORE_PASSWORD}
       # If the private key password differs from the keystore password, read it from an environment variable as well.
       key-password: ${SSL_KEY_PASSWORD}
   
       # --- Security configuration: TLS protocols and cipher suites ---
       # Enable secure TLS protocol versions.
       enabled-protocols: TLSv1.2,TLSv1.3
       # Configure recommended strong cipher suites.
       ciphers:
         - TLS_AES_256_GCM_SHA384
         - TLS_CHACHA20_POLY1305_SHA256
         - TLS_AES_128_GCM_SHA256
         - ECDHE-RSA-AES256-GCM-SHA384
         - ECDHE-RSA-AES128-GCM-SHA256
   
     # Enable HTTP/2 to improve performance.
     http2:
       enabled: true

Step 3: Configure the system and network environment

Ensure your security group and system firewall allow inbound traffic on the HTTPS port (443).

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

   RHEL/CentOS

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

   If the output is Ncat: Connected to <The public IP address of the current server>:443, port 443 is open. Otherwise, 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> with your server's actual public IP address.
   sudo ss -tlnp | grep -q ':443 ' || sudo nc -l -p 443 & sleep 1; nc -w 3 -vz <your_server_public_ip> 443

   If the output is Connection to <public IP address of the current server> port [tcp/https] succeeded! or [<public IP address of the current server>] 443 (https) open, port 443 is open. Otherwise, open port 443 in the security group and firewall.

2. Open port 443 in your security group configuration.

   Important

   If your server is deployed on a cloud platform, ensure its security group allows inbound traffic on TCP port 443. Otherwise, the service will be inaccessible. The following steps use Alibaba Cloud Elastic Compute Service (ECS) as an example. For other cloud platforms, refer to their official documentation.

   Go to the Elastic Compute Service instance page, click the target instance name to go to the instance details page. Refer to Add a security group rule to add a new rule in the Security Group with the Action set to Allow, Protocol Type to Custom TCP, Destination Port Range to HTTPS(443), and Authorization Object to All IPv4 Addresses.

3. Open port 443 in your firewall.

   Run the following command to identify the active 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, run the corresponding command below based on the output (firewalld, ufw, nftables, or iptables) 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 ensure the iptables rules persist after a system reboot, run the following commands:

   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

Step 4: Restart the application

Go to the root directory of your Spring Boot project. Based on your build tool, run the corresponding command to restart the application.

# 1. Find and stop the running application process (PID).
# ps -ef | grep your-app-name.jar
# kill <PID>
#
# 2. Restart the application. If you need to add JVM arguments, include them before '&'.
nohup java -jar /path/to/your-app-name.jar &

Step 5: Verify the deployment

Going live

When deploying to a production environment, follow these best practices to enhance security, stability, and maintainability:

• Run as a non-administrator user:

  Create a dedicated, low-privilege system user for the application. Never run the application with an account that has administrator privileges.

  Note

  A recommended approach is to configure SSL at the gateway layer. This involves deploying the certificate on a Server Load Balancer (SLB) or a reverse proxy such as Nginx. The gateway terminates the HTTPS traffic and forwards the decrypted HTTP traffic to the backend application.

• Externalize credential management:

  Never hard-code passwords or other sensitive information in your code or configuration files. Use environment variables, Vault, or a cloud provider's key management service to inject credentials.

• Enforce HTTP to HTTPS redirection:

  Redirect all HTTP traffic to HTTPS to prevent man-in-the-middle attacks.

• Configure modern TLS protocols:

  Disable old and insecure protocols (such as SSLv3, TLSv1.0, and TLSv1.1) in your server configuration. Enable only TLSv1.2 and TLSv1.3.

• Monitor certificates and automate renewal:

  After deploying the certificate, enable domain monitoring. Alibaba Cloud automatically checks the certificate validity period and sends renewal reminders before expiration to help you avoid service disruptions. For more information, see Purchase and enable public domain name monitoring.

Why is my certificate not working or HTTPS inaccessible after installation or update?

This issue is often caused by one of the following configuration problems. Check them in order:

• Port 443 is blocked: The server's security group or firewall does not have port 443 open. See Configure the system and network environment.

• Domain mismatch: The domain you are accessing is not listed in the certificate's Bound Domains. See Domain Name Matching.

• Spring Boot not restarted: The Spring Boot service was not restarted after you modified the configuration file. See Step 4: Restart the application.

• Incorrect certificate configuration: The certificate files were not replaced correctly, or the certificate path is not specified correctly in the Spring Boot configuration. Check whether the Spring Boot configuration file and the certificate file are the latest and valid.

• Missing certificate on other services: If your domain uses services such as a Content Delivery Network (CDN), Server Load Balancer (SLB), or Web Application Firewall (WAF), the certificate must also be installed on those services. See Certificate deployment locations when traffic passes through multiple Alibaba Cloud services to complete the setup.

• Incomplete deployment on multiple servers: If your domain's DNS resolves to multiple servers, the certificate must be installed on all of them.

What is the correct way to update or replace an SSL certificate in a Spring Boot application?

1. Back up old files: Back up the existing certificate and password files on your server.

2. Get new files: Download the new certificate and private key files from your Certificate Management Service console.

3. Replace files: Upload the new files to your server, overwriting the old ones. Ensure the new files have the exact same path and filename as the ones specified in your Spring Boot configuration.

4. Restart Spring Boot: Restart Spring Boot to apply the new certificate.