Require client certificates for your API with mutual TLS authentication in API Gateway
Mutual TLS authentication requires two-way authentication between the client and the server. With mutual TLS, clients must present X.509 certificates to verify their identity to access your API. Mutual TLS is a common requirement for Internet of Things (IoT) and business-to-business applications.
You can use mutual TLS along with other authorization and authentication operations that API Gateway supports. API Gateway forwards the certificates that clients provide to Lambda authorizers and to backend integrations.
Important
By default, clients can invoke your API by using the execute-api endpoint
that API Gateway generates for your API. To ensure that clients can access
your API only by using a custom domain name with mutual TLS, disable the default
execute-api endpoint. To learn more, see Disable the default endpoint for REST APIs.
Topics
Prerequisites for mutual TLS
To configure mutual TLS you need:
A Regional custom domain name
At least one certificate configured in AWS Certificate Manager for your custom domain name
A truststore configured and uploaded to Amazon S3
Custom domain names
To enable mutual TLS for a REST API, you must configure a custom domain name for your API. You can enable mutual TLS for a custom domain name, and then provide the custom domain name to clients. To access an API by using a custom domain name that has mutual TLS enabled, clients must present certificates that you trust in API requests. You can find more information at Custom domain name for public REST APIs in API Gateway.
Using AWS Certificate Manager issued certificates
You can request a publicly trusted certificate directly from ACM or import public
or self-signed certificates. To setup a certificate in ACM, go to ACM
Using an imported or AWS Private Certificate Authority certificate
To use a certificate imported into ACM or a certificate from AWS Private Certificate Authority with mutual TLS, API Gateway needs an
ownershipVerificationCertificate issued by ACM. This ownership certificate is only used to
verify that you have permissions to use the domain name. It is not used for the TLS handshake. If you don't
already have a ownershipVerificationCertificate, go to https://console.aws.amazon.com/acm/
You will need to keep this certificate valid for the lifetime of your domain name. If a certificate
expires and auto-renew fails, all updates to the domain name will be locked. You will need to update the
ownershipVerificationCertificateArn with a valid ownershipVerificationCertificate
before you can make any other changes. The ownershipVerificationCertificate cannot be used as a
server certificate for another mutual TLS domain in API Gateway. If a certificate is directly re-imported into
ACM, the issuer must stay the same.
Configuring your truststore
Truststores are text files with a .pem file extension. They are a trusted list of certificates
from Certificate Authorities. To use mutual TLS, create a truststore of X.509 certificates that you trust to
access your API.
You must include the complete chain of trust, starting from the issuing CA certificate, up to the root CA certificate, in your truststore. API Gateway accepts client certificates issued by any CA present in the chain of trust. The certificates can be from public or private certificate authorities. Certificates can have a maximum chain length of four. You can also provide self-signed certificates. The following algorithms are supported in the truststore:
SHA-256 or stronger
RSA-2048 or stronger