How do I troubleshoot API Gateway errors when I use SSL certificates with backend integration?

Short description

When API Gateway performs an SSL handshake with the backend, API Gateway expects the backend to provide certificates from trusted issuers. API Gateway expects the certificates to be valid, and not expired. API Gateway also expects the chain of trust to be intact. This means that API Gateway expects the certificate to contain a root certificate authority (CA), intermediate CAs, and the parent certificate details. With this information, API Gateway can complete certificate validation when it goes through the chain of certificates.

Resolution

Test HTTP proxy integration

To familiarize yourself with HTTP proxy integrations, test bad SSL certificates from the API Gateway console. For more information about bad SSL certificates and for testing, see the Bad SSL website.

1. Create a resource named /selfsigned with a GET method. Then, configure an HTTP proxy integration with the URL https://self-signed.badssl.com/.

   From the API Gateway console, test the API. You receive the following error:

   "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"

2. Create a resource named /expiredcert with a GET method. Then, configure an HTTP proxy integration with the URL https://expired.badssl.com/.

   From the API Gateway console, test the API. You receive the following error:

   "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"

3. Create a resource named /untrustedRootCA with a GET method. Configure an HTTP proxy integration with the URL https://untrusted-root.badssl.com/.

   From the API Gateway console, test the API. You receive the following error:

   "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"

Resolve a "PKIX path building failed" error

With VPC link integration, API Gateway performs certificate validation with the next hop that performs TLS termination. 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 are installed on the target instances. The Network Load Balancer and the target groups are bound within a VPC and communications are secure. If the Network Load Balancer uses a TCP listener, then the TLS handshake happens end-to-end. In these cases, the backend application must comply with the SSL requirements.

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

When API Gateway can't validate the certificate authority (CA) of your backend Network Load Balancer certificate, 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"

If you receive the PKIX path building failed error, then you might have one of the following certificate issues:

• Incomplete certificate chain: If your SSL certificate doesn't include the expected intermediate certificates or the full certificate chain isn't present, then certificate validation fails.
• Unsupported CA: If the certificate isn't issued by a CA that API Gateway supports, then the validation fails. This is also true for self-signed or private certificates that aren't issued by a CA.

To troubleshoot this issue, follow these steps:

Turn on "insecureSkipVerification"

Note: It's not a best practice to use this method for production use cases.

Set the insecureSkipVerification option to true for the specific integration that results in an error. Note that only HTTP and HTTP_PROXY integrations support this setting. When you set this option to true, API Gateway skips CA verification for the integration endpoint's certificate. This also allows you to use a self-signed certificate or one from a private CA.

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

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"

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.

Verify that the certificate chain is complete

To check if the certificate path chain is complete, run the following OpenSSL command:

Note: To run this command, you must install OpenSSL. For more information, see the OpenSSL website.

$ openssl s_client -servername example.com -connect example.com:443

For more information, see s_client on the OpenSSL website.

If your certificate chain is complete, then the command returns verify ok. Otherwise, the output indicates an incomplete certificate chain for any type of certificate (supported or unsupported CAs).

Note: Additionally, make sure that your integration URI in the API Gateway with the Network Load Balancer uses a valid top-level domain (TLD). The API Gateway console might not allow endpoint URLs that end with specific domain extensions.

Related information

Generate and configure an SSL certificate for backend authentication

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

Target groups for your Network Load Balancers

Generate and configure an SSL certificate for backend authentication