How do I resolve certificate subject conflicts with mutual TLS in API Gateway?

Short description

When you configure mTLS authentication for an API Gateway custom domain, you might get an error that indicates a conflict in certificate subjects. This error looks similar to the following example:

"The certificate subject conflicts with an existing certificate from a different issuer."

This issue occurs when there are multiple certificates with conflicting subjects. To resolve this issue and issues with authentication, follow these troubleshooting steps for common causes.

Resolution

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

Multiple Certificate Authorities

If multiple Certificate Authorities (CAs) issued certificates for the same domain, then you get this error. API Gateway requires that each subject in the certificate must correspond to a single issuer for mTLS domains.

To resolve this issue, take these actions:

• For all certificates that you associate with the same domain subject, make sure that you obtain the certificates from a single CA.
• For any certificates that other AWS accounts in your organization issue, review the certificates to make sure that they don't conflict.

To check certificates in your account, run the following command in the AWS CLI:

openssl s_client -connect YOUR_CUSTOM_DOMAIN:443 -servername SANS/CN_IN_CERTIFICATE | openssl x509 -noout -text

Note: Replace YOUR_CUSTOM_DOMAIN with your domain name and SANS/CN_IN_CERTIFICATE with the Subject Alternative Name (SAN) or Common Name (CN) for your SSL certificate.

Deleted or outdated certificates

You can receive this error even when you don't see other conflicting certificates because you have deleted or outdated certificates in your configuration.

To resolve this issue, take these actions:

• Check if you have any deleted or revoked certificates that conflict with other certificates.
• Confirm that the specified certificate is available and active.

To check certificate information, run the following command in the AWS CLI:

aws acm describe-certificate --certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/your-placeholder-arn

Note: Replace certificate-arn with your certificate's full ARN.

Conflicting certificates from different issuers

When you transition from external SSL certificates to AWS Certificate Manager (ACM) certificates for mTLS, you might get this error. In this case, you have certificates from different issuers that are associated with the same domain subject.

To resolve this issue and prevent future issues, take these actions:

• Consolidate all certificates that share the same subject under a single issuer.
• Plan for potential downtime when you switch from one issuer to another.