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

Short description

If you configure mTLS for a custom domain in API Gateway, then you might have certificates from different Certificate Authorities (CAs) for the same domain subject. You get the following error message:

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

The error might occur for AWS Certificate Manager (ACM) certificates, externally imported certificates from other CAs, and certificates from different AWS accounts in the same organization.

To resolve this issue, make sure that you obtain all certificates associated with the same domain subject from a single CA source.

Resolution

Verify certificate details

API Gateway doesn't allow certificates for the same domain subject from multiple issuers within the same AWS Region. To check certificate information for your custom domain, run the following OpenSSL command:

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) from the certificate.

It's a best practice to use ACM certificates in the SAN for all mTLS custom domains in the same API Gateway Region.

Check for conflicts with certificates and domains

If you use wildcard certificates, then use different wildcard certificates from the same issuer to separate subdomains. Wildcard certificates, such as *.example.com, might cause ownership verification problems. It's a best practice not to use wildcard certificates.

If you have multiple AWS accounts in your organization, then check for conflicting mTLS domains. Make sure that the mTLS domains don't use wildcard certificates from different issuers across those accounts within the same Region.

Check for deleted or outdated certificates

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.

If you deleted or have outdated certificates in your configuration, then you might receive the "Certificate subject conflicts" error.

Check if you have deleted or revoked certificates that conflict with other certificates. To check certificate information, run the following describe-certificate AWS CLI command:

aws acm describe-certificate --certificate-arn arn:aws:acm:Region:accountID:certificate/certificateID

Note: Replace Region with the Region, accountID with your account ID, and certificateID with the details from your certificate's Amazon Resource Name (ARN).

Confirm that the specified certificate is available and active.

Validate your certificate expiration dates. If your certificate is expired, then force a certificate renewal.

Related information

How to turn on mutual TLS authentication for your REST APIs in API Gateway

What is AWS Certificate Manager?