When testing REST APIs over HTTPS, REST Assured provides a simple and fluent interface to interact with APIs. However, testing against servers with untrusted or self-signed SSL certificates can result in SSL handshake failures. Let us delve into understanding how REST Assured HTTPS connections to untrusted servers can be managed securely and effectively. While relaxed validation helps in quick testing scenarios, explicitly trusting certificates is the recommended and safer approach for production-grade environments.

1. Introduction

When testing REST APIs over HTTPS, REST Assured provides a simple and fluent interface to interact with APIs. However, testing against servers with untrusted or self-signed SSL certificates can result in SSL handshake failures. Let us delve into understanding how REST Assured HTTPS connections to untrusted servers can be managed securely and effectively. While relaxed validation helps in quick testing scenarios, explicitly trusting certificates is the recommended and safer approach for production-grade environments.

1.1 Dependencies

To use REST Assured in your Java project, include the following Maven dependency in your pom.xml:

<dependencies>
 <dependency>
 <groupId>io.rest-assured</groupId>
 <artifactId>rest-assured</artifactId>
 <version>latest__jar__version</version>
 <scope>test</scope>
 </dependency>
</dependencies>

This dependency provides the core REST Assured library, which supports fluent API testing over HTTPS. Make sure your project is configured to use a compatible Java version (Java 8 or higher) for SSL features.

2. Handling Test Failures Caused by Untrusted SSL Certificates

By default, REST Assured relies on Java’s default SSL settings. If the server’s SSL certificate is self-signed or untrusted, your test will fail with an javax.net.ssl.SSLHandshakeException. For example: The following code attempts to make an HTTPS GET request to a server with an untrusted SSL certificate.

import io.restassured.RestAssured;
import io.restassured.response.Response;

public class UntrustedSSLExample {
 public static void main(String[] args) {
 Response response = RestAssured.get("https://untrusted-server.com/api/data");
 System.out.println(response.getStatusCode());
 }
}

This code sends a simple GET request using REST Assured to an HTTPS endpoint. However, since the SSL certificate of the target server is not trusted by Java’s default truststore, the request fails during the SSL handshake process, resulting in an exception. The below output shows the typical exception thrown when the SSL validation fails.

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed

This error indicates that the SSL handshake could not be completed because Java could not validate the certificate path for the server, commonly due to missing or self-signed certificates.

3. Bypassing SSL Verification with Relaxed HTTPS Validation

REST Assured provides a convenient way to bypass SSL validation using relaxedHTTPSValidation(). This is useful for testing environments with self-signed certificates. The following code demonstrates how to disable SSL certificate validation while making an HTTPS call using REST Assured.

import io.restassured.RestAssured;
import io.restassured.response.Response;

public class RelaxedSSLExample {
 public static void main(String[] args) {
 Response response = RestAssured
 .given()
 .relaxedHTTPSValidation()
 .get("https://untrusted-server.com/api/data");

 System.out.println("Status Code: " + response.getStatusCode());
 System.out.println("Response Body: " + response.getBody().asString());
 }
}

This example uses the relaxedHTTPSValidation() method, which allows REST Assured to ignore SSL certificate validation errors. As a result, even if the certificate is self-signed or untrusted, the request completes successfully and returns the actual response from the server. The below output shows the response obtained when the SSL check is relaxed.

Status Code: 200
Response Body: {"id":1,"name":"Test Data"}

As seen above, the request executes successfully and prints the response data from the server, confirming that SSL validation was bypassed during the call.

4. Configuring REST Assured to Trust Specific SSL Certificates

For a more secure approach, you can explicitly trust a specific certificate instead of bypassing validation entirely. You need to load the certificate into a Java KeyStore and configure REST Assured to use it. The following code demonstrates how to trust a particular SSL certificate by loading it into a Java KeyStore and configuring REST Assured with a custom SSL context.

import io.restassured.RestAssured;
import io.restassured.specification.RequestSpecification;

import javax.net.ssl.SSLContext;
import java.io.FileInputStream;
import java.security.KeyStore;

import javax.net.ssl.TrustManagerFactory;

public class TrustCertExample {
 public static void main(String[] args) throws Exception {
 // Load the certificate into a KeyStore
 KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
 FileInputStream fis = new FileInputStream("trustedCert.jks");
 trustStore.load(fis, "password".toCharArray());

 // Initialize TrustManagerFactory with the KeyStore
 TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
 tmf.init(trustStore);

 // Setup SSLContext with trusted certificate
 SSLContext sslContext = SSLContext.getInstance("TLS");
 sslContext.init(null, tmf.getTrustManagers(), null);

 // Configure REST Assured to use the SSLContext
 RequestSpecification spec = RestAssured
 .given()
 .sslConfig(RestAssured.config().sslConfig(
 RestAssured.config().getSSLConfig().sslSocketFactory(sslContext.getSocketFactory())
 ));

 String response = spec.get("https://trusted-server.com/api/data").asString();
 System.out.println("Response: " + response);
 }
}

This code securely configures REST Assured to communicate with a trusted server by loading a specific certificate from a Java KeyStore. It sets up a custom SSLContext with the trusted certificate and applies it to REST Assured’s SSL configuration, ensuring that only recognized certificates are accepted during HTTPS communication. The output below shows the response received from the trusted server.

Response: {"id":1,"name":"Trusted Data"}

The output confirms that the HTTPS call succeeded using the trusted certificate, demonstrating a secure and recommended approach for handling SSL in automated tests.

5. Conclusion

Handling SSL certificates correctly is crucial when making HTTPS calls in test environments using REST Assured. While untrusted SSL certificates can cause SSLHandshakeException errors, REST Assured provides flexible options to handle such scenarios.
For quick testing, relaxedHTTPSValidation() allows bypassing SSL verification, which is convenient but not secure for production systems. A better practice is to trust specific certificates by configuring a custom SSLContext with a Java KeyStore, ensuring that the connection remains both valid and secure. In summary, use relaxed HTTPS validation only in controlled or non-production setups, and always prefer trusting certificates explicitly for secure and reliable API testing workflows.