Resolving 'Bad Request - This combination of host and port requires TLS' Error in Spring Boot

Problem Background and Phenomenon Analysis

During Spring Boot application development, developers often encounter the error message 'Bad Request - This combination of host and port requires TLS' when configuring SSL/TLS encrypted connections. This error typically occurs when the application server has enabled SSL configuration, but the client still attempts to access using the HTTP protocol.

From the provided case study, the developer first attempted to access using http://localhost:8081/points/12345/search. At this point, the server detected that the port was configured for SSL, but the client was not using the TLS protocol, thus returning an error response. When the developer switched to using the https:// protocol prefix, connection failures occurred, indicating potential issues with the SSL configuration itself.

Detailed Explanation of SSL Configuration Parameters

In the application.properties file, key SSL configuration parameters include:

server.ssl.key-store=classpath:KeyStore.jks
server.ssl.key-store-password=test
server.ssl.key-alias=homologation-staging
server.ssl.trust-store=classpath:TrustStore.jks
server.ssl.trust-store-password=test
server.ssl.client-auth=need
security.require-ssl=true

The specific meanings of these configuration parameters are as follows:

• server.ssl.key-store: Specifies the path to the keystore file containing the server's private key
• server.ssl.key-store-password: The access password for the keystore
• server.ssl.key-alias: The alias identifying a specific key within the keystore
• server.ssl.trust-store: The path to the truststore file containing trusted certificates
• server.ssl.client-auth: Configures client authentication requirements, where 'need' indicates mandatory client certificate verification
• security.require-ssl: Forces all requests to use SSL

Root Cause Analysis

The core of the problem lies in protocol mismatch. When a Spring Boot application configures SSL parameters, the server enables HTTPS service on the specified port, which then only accepts TLS encrypted connections. Any attempts to access this port using the plain HTTP protocol will be rejected with corresponding error messages.

From a technical implementation perspective, Spring Boot's embedded Tomcat server automatically configures the corresponding port as an SSL connector when it detects SSL configuration. At this point, traditional HTTP connectors are either disabled or redirected to ensure all communication undergoes encryption processing.

Solutions and Implementation Steps

Based on best practices and problem analysis, the correct solution includes the following key steps:

1. Using the Correct Protocol Prefix

The most fundamental and crucial solution is to ensure using https:// instead of http:// as the URL prefix. This is the most direct method to resolve the 'Bad Request - This combination of host and port requires TLS' error.

// Incorrect access method
http://localhost:8081/points/12345/search

// Correct access method  
https://localhost:8081/points/12345/search

2. Verifying SSL Configuration Integrity

Ensure all SSL-related configuration parameters are correct, particularly the keystore file path, password, and alias settings. The keystore file must be located in the classpath, and the password must match the one set when creating the keystore.

3. Handling Self-Signed Certificate Issues

Referring to certificate verification issues mentioned in supplementary materials, when using self-signed certificates, ensure the certificates include correct Subject Alternative Names (SANs). If the certificate does not contain the IP address or domain name used for access, SSL handshake failures may occur.

For development environments, consider the following solutions:

• Include localhost as a SAN in the certificate
• Use correct DNS names instead of IP addresses for access
• Configure trust for self-signed certificates in the client

4. Client Authentication Configuration

When server.ssl.client-auth is set to 'need', the client must provide a valid certificate for authentication. During development and testing phases, this parameter can be temporarily set to 'want' or 'none' to simplify the debugging process.

Code Examples and Best Practices

The following is a complete Spring Boot SSL configuration example, demonstrating how to correctly set SSL parameters and handle related exceptions:

@SpringBootApplication
public class SecureApplication {
    
    @Bean
    public ServletWebServerFactory servletContainer() {
        TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory();
        tomcat.addAdditionalTomcatConnectors(createSslConnector());
        return tomcat;
    }
    
    private Connector createSslConnector() {
        Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
        Http11NioProtocol protocol = (Http11NioProtocol) connector.getProtocolHandler();
        
        try {
            connector.setScheme("https");
            connector.setSecure(true);
            connector.setPort(8081);
            protocol.setSSLEnabled(true);
            protocol.setKeystoreFile(getClass().getClassLoader()
                .getResource("KeyStore.jks").getFile());
            protocol.setKeystorePass("test");
            protocol.setKeyAlias("homologation-staging");
            return connector;
        } catch (Exception ex) {
            throw new IllegalStateException("Failed to create SSL connector", ex);
        }
    }
    
    public static void main(String[] args) {
        SpringApplication.run(SecureApplication.class, args);
    }
}

Testing and Verification Methods

To ensure SSL configuration works correctly, adopt the following testing strategy:

1. Use a browser to access https://localhost:8081, observing certificate warnings and connection status
2. Use Postman or curl tools to test API endpoints, ensuring TLS connections can be established
3. Check server logs to confirm SSL connectors have started correctly
4. Verify client certificate authentication (if configured) works properly

Summary and Recommendations

The key to resolving the 'Bad Request - This combination of host and port requires TLS' error lies in understanding the essential requirements of SSL configuration. Once an application configures SSL parameters, HTTPS protocol must be used for access. Simultaneously, ensure certificate configuration correctness, particularly in development environments using self-signed certificates.

For production environments, recommend using certificates issued by authoritative certificate authorities and ensuring certificates include all necessary SAN entries. Regularly reviewing and updating SSL configurations, maintaining consistency with the latest security standards, are important measures to ensure application security.