How do I troubleshoot API Gateway SSL certificate errors with backend integration?

Resolution

Test HTTP proxy integration

Use the API Gateway console to test bad SSL certificates. For a list of bad SSL certificates, see badssl.com on the Bad SSL website.

Complete the following steps:

1. Create a resource that's named /selfsigned.
2. Create a GET method on the resource.
3. Configure an HTTP proxy integration with the URL.
4. Open the API Gateway console.
5. Test the API.
6. Repeat each of the preceding steps with a resource that's named /expiredcert and then another resource that's named /untrustedRootCA.

For the resource that's named /selfsigned, you receive the following error message:

"Thu Dec 15 16:05:05 UTC 2022 : Sending request to https://self-signed.badssl.com/

Thu Dec 15 16:05:05 UTC 2022 : Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

For the resource that's named /expiredcert, you receive the following error message:

"Thu Dec 15 16:06:02 UTC 2022 : Sending request to https://expired.badssl.com/

Thu Dec 15 16:06:02 UTC 2022 : Execution failed due to configuration error: PKIX path validation failed: java.security.cert.CertPathValidatorException: validity check failed"

For the resource that's named /untrustedRootCA, you receive the following error message:

"Thu Dec 15 16:06:28 UTC 2022 : Sending request to https://untrusted-root.badssl.com/

Thu Dec 15 16:06:28 UTC 2022 : Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

Troubleshoot HTTP proxy integration test errors

If you receive an error when you test HTTP proxy integration, then follow these troubleshooting steps.

"Execution failed due to configuration error: Unrecognized SSL message"

This error occurs when you try to establish an SSL connection with a backend that expects HTTP requests, and you used an HTTPS endpoint URL. To resolve this error, update the endpoint URL to use HTTP instead of HTTPS.

"400 Bad Request:You're speaking plain HTTP to an SSL-enabled server port"

This error occurs when you try to establish an SSL connection with a backend that expects HTTP requests, and you used an HTTPS endpoint URL. To resolve this error, update the endpoint URL to use HTTPS instead of HTTP.

Resolve configuration errors

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

When a Network Load Balancer has a TLS listener, the Network Load Balancer performs a TLS termination and creates another connection to the target. The certificate that's attached to the Network Load Balancer must meet all the requirements.

A Network Load Balancer doesn't perform certificate validation during the SSL handshake with the target. The Network Load Balancer accepts expired or self-signed certificates that you installed on the target instances. The Network Load Balancer and the target groups are linked within a virtual private cloud (VPC). If the Network Load Balancer uses a TCP listener, then the TLS handshake happens end to end. In this case, the backend application must meet the SSL requirements.

API Gateway supports Server Name Indication (SNI) during an SSL handshake over a VPC link integration.

If the backend Network Load Balancer has a self-signed or private certificate that a certificate authority (CA) didn't issue, then you receive the following error:

"Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

To resolve this issue, run the following update-integration AWS CLI command, and set insecureSkipVerification to true in the integration's tlsConfig object:

aws apigateway update-integration --rest-api-id EXAMPLE-REST-API-ID --resource-id EXAMPLE-RESOURCE-ID --http-method GET --patch-operations "op='replace',path='/tlsConfig/insecureSkipVerification',value=true"

Note: Replace EXAMPLE-REST-API-ID and EXAMPLE-RESOURCE-ID with your values.

When you turn on insecureSkipVerification, API Gateway still performs basic certificate validation. This validation includes verification for the certificate's expiration date, hostname, and the presence of a root CA.

Related information

Generate and configure an SSL certificate for backend authentication in API Gateway

API Gateway-supported certificate authorities for HTTP and HTTP proxy integrations

Target groups for your Network Load Balancers