Utilizing ACM Private CA for Mutual TLS in Amazon API Gateway

More Info

In a recent update, Amazon API Gateway introduced certificate-based mutual Transport Layer Security (TLS) authentication. This method, known as mutual TLS (mTLS), ensures that not only does the server authenticate the client, but the client must also provide an X.509 certificate to verify its identity. This dual-authentication mechanism enhances the security of interactions between both parties. For those interested in learning about setting up TLS using a root CA generated with OpenSSL, you can refer to a previous post. However, many users have expressed the need for a guide that details how to implement this using AWS Certificate Manager Private Certificate Authority (ACM Private CA).

In this article, I will guide you through the process of configuring API Gateway for mutual TLS with ACM Private CA. We will go through how to retrieve the public key from the ACM Private CA certificate and utilize it within API Gateway to establish a secure connection between the server and client. By linking the public key of the root CA to the API Gateway endpoint, you enable the endpoint to trust any certificate issued by that CA or any subordinate CA associated with the root CA. This streamlines the management process by eliminating the need to provide a list of individual client certificates that API Gateway needs to trust.

Please note that you’ll need the public keys of the root CA and any intermediate CAs you’ve created, as these must be uploaded to API Gateway for proper authentication.

Prerequisites

Before proceeding with this guide, ensure you have the following:

• An AWS account.
• A domain name that you own.
• An AWS Certificate Manager public certificate for your custom domain.
• An AWS Certificate Manager Private CA in the same AWS region as your Amazon API Gateway, specifically in us-east-1.

Retrieving Your ACM Private CA Root CA Certificate Public Key

In this guide, we will utilize a single root CA to generate your certificate for mutual TLS authentication. You will only need to upload the RootCA.pem file to your Amazon S3 bucket. If you have an intermediary CA, you should also upload that certificate file.

Start by retrieving the public key from your root CA certificate and creating the PEM-encoded trust store file. Follow the steps below, ensuring you substitute each placeholder with your specific resource information.

1. To fetch the certificate authority certificate, run the following command in your terminal, replacing account_id and certificate_authority_id with your actual values:

$ aws acm-pca get-certificate-authority-certificate --certificate-authority-arn arn:aws:acm-pca:us-east-1:account_id:certificate-authority/certificate_authority_id --output text > certificate.pem

2. To extract the public key from the certificate, execute this OpenSSL command:

$ openssl x509 -pubkey -noout -in certificate.pem > pubkey.pem

3. To create the PEM-encoded trust store file that contains the certificate authority public key, run:

$ cp pubkey.pem truststore.pem

4. Upload the trust store file to an Amazon S3 bucket in the same AWS account and region as your API Gateway API:

$ aws s3 mb s3://my-example-truststore --region us-east-1 # Creates new bucket
$ aws s3api put-bucket-versioning --bucket my-example-truststore --versioning-configuration Status=Enabled # Enables versioning
$ aws s3 cp truststore.pem s3://my-example-truststore/ truststore.pem # Uploads the object to the bucket

Note: It is advisable to enable object versioning for the bucket. In this guide, we will create a new S3 bucket, enable versioning, and upload your truststore.pem file.

Generating a Client Certificate

To test the setup, you will need to generate a certificate from your ACM Private CA. Follow these steps:

1. Generate the CSR for your certificate request with the command below, which will provide you with both the RSA private key and the CSR:

$ openssl req -new -newkey rsa:2048 -days 365 -keyout my_client.key -out my_client.csr

2. Now that you have the private key and CSR, request a certificate from ACM Private CA using the command below, making sure to replace account_id and certificate_authority_id with your values:

$ aws acm-pca issue-certificate --certificate-authority-arn arn:aws:acm-pca:us-east-1:account_id:certificate-authority/certificate_authority_id --csr fileb://my_client.csr --signing-algorithm "SHA256WITHRSA" --validity Value=365,Type="DAYS" --template-arn arn:aws:acm-pca:::template/EndEntityCertificate/V1

This command will return the certificate ARN.

3. To retrieve the certificate, use the ARN in the following command. Replace the account_id, certificate_authority_id, and certificate_id with your own values:

$ aws acm-pca get-certificate --certificate-authority-arn arn:aws:acm-pca:us-east-1:account_id:certificate-authority/certificate_authority_id --certificate-arn arn:aws:acm-pca:us-east-1:account_id:certificate-authority/certificate_authority_id/certificate/certificate_id --output text

Save the retrieved certificate as my_client.pem. Now that you have your root CA’s public key uploaded to your truststore S3 bucket and your certificate, we can proceed to enable mutual TLS on your API Gateway.

Enabling Mutual TLS on Your Custom Domain Name

With your root CA’s key stored in your S3 bucket as a truststore, and a certificate for your custom domain, you can configure mutual TLS for your API Gateway. First, log into your API Gateway console in the AWS Management Console, specifically in the us-east-1 region. Follow the steps below:

1. Access your API Gateway console in the us-east-1 Region.
2. In the left menu, select Custom domain names.
3. Click Create on the Custom domain names pane.
4. On the Domain details pane, enter your custom domain name. Under Minimum TLS version, select TLS 1.2 (recommended) and Mutual TLS authentication. For the Truststore URI, input the URI of the truststore you created, formatted as s3://my-example-truststore/truststore.pem. Remember to replace my-example-truststore and truststore.pem with your values. Optionally, specify the version of the truststore.pem for version control.

For additional insights, check out this blog post for further reading.

For expert guidance on this subject, visit this authority that provides comprehensive information. You can also look into this excellent resource for related topics.