How to use AWS Certificate Manager with AWS CloudFormation

December 11, 2024: This post has been updated with AWS CloudFormation templates to issue AWS Certificate Manager (ACM) public certificates, as well as AWS private certificates (using ACM).

In July 2020, Amazon Web Services (AWS) introduced the ability to automate issuing and validating public and private certificates using AWS CloudFormation.

To make this easier, AWS has introduced three new features that let you:

• Automate the steps to validate your domain with DNS validation and issue your public certificate.
• Use AWS CloudFormation templates to issue private certificates using AWS Certificate Manager (ACM).
• Disable certificate transparency logging if you don’t want your certificates automatically logged in a public certificate transparency log.

In this post, we will discuss how these features are used with CloudFormation templates and provide sample templates to help you request ACM certificates.

Automate issuing a public DNS validated certificate

Before ACM can issue a certificate for your site, ACM must verify that you own or control all of the domain names that you specified in your request. Valid verification methods are either email validation or DNS validation when you request a certificate.

Previously, when you requested DNS validation, you had to manually add the requested CNAME validation record to the hosted zone in Amazon Route 53. ACM uses canonical name (CNAME) records to validate domain ownership.

CloudFormation validates your ACM public certificate using the DNS validation method when a CloudFormation stack is run from the same AWS account and domain that is registered with Route 53. To enable this feature, you need to reference your HostedZoneIdto create the required CNAME record for validation.

When you use the AWS::CertificateManager::Certificate resource in a CloudFormation stack, domain validation is handled automatically if all of the following conditions are met: The domain is hosted in Amazon Route 53, the domain resides in your AWS account, and you are using the DNS validation method.

If the certificate uses email validation, or if the domain is not hosted in Route 53, then the stack will remain in the CREATE_IN_PROGRESS state. Further stack operations are delayed until you validate the certificate request, either by acting upon the instructions in the validation email, or by adding a CNAME record to your DNS configuration.

Following is example CloudFormation YAML code for issuing a public ACM certificate without subject alternative names (SANs):

Resources:
  ACMCertificateValidation:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: example.com
      DomainValidationOptions:
        - DomainName: example.com
          HostedZoneId: XXXXXXXXXX12345
      ValidationMethod: DNS

Following is example code for issuing a public ACM certificate with subject alternative names:

Resources:
  ACMCertificateValidation:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: example1.com
      ValidationMethod: DNS
      DomainValidationOptions:
        - DomainName: example1.com
          HostedZoneId: XXXXXXXXXX12345
        - DomainName: example2.in
          HostedZoneId: YYYYYYYYYY67890
      SubjectAlternativeNames:
        - example2.in

Note: A CNAME record will not be created in HostedZone and the stack will remain in the CREATE_IN_PROGRESS state in the scenario where a public certificate is requested for a subdomain and you have referenced a hosted zone for the parent domain. For example, when you request an ACM certificate for test.example.com and you are referencing the hosted zone example.com, the CloudFormation stack will remain in the CREATE_IN_PROGRESS state.

When you deploy this resource in AWS CloudFormation, you’ll see the required CNAME record issued by ACM. AWS CloudFormation will use this information to update the hosted zone based on the HostedZoneId you provided. The following figure shows the CNAME listed in the Status reason of the Events list.

Figure 1: ACM automation events list

Now you can automate using ACM to issue public certificates and include that as part of your overall stack. For more information, see AWS::CertificateManager::Certificate.

Disable certificate transparency

If clients need certificate transparency to be disabled, you can include disabling of the certificate transparency logs as part of your AWS CloudFormation template.

Certificate transparency is an open framework that monitors and audits SSL/TLS certificates. The standard creates a system of public logs that will eventually record all certificates issued by publicly trusted certificate authorities, allowing efficient identification of mistakenly or maliciously issued certificates. Every certificate transparency log is a record of all publicly trusted digital certificates unless you specifically disable certificate transparency at creation. Those certificates contain information about the public key, the subject, and the issuer.

Certificate transparency logs keep append-only cryptographically-secured records of certificates, meaning that certificates can only be added to the log. It’s impossible to delete, modify, or in any way retroactively change or insert certificates into the log.

If there is a client requirement to disable certificate transparency, you can do so using the CloudFormation template. You will need to add the CertificateTransparencyLoggingPreference parameter and set it to ENABLED or DISABLED.

Following is example CloudFormation YAML code that includes the CertificateTransparencyLoggingPreference parameter:

Resources:
  ACMCertificateValidation:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: example4.com
      DomainValidationOptions:
        - DomainName: example.com
          HostedZoneId: XXXXXXXXXX12345
      ValidationMethod: DNS
      CertificateTransparencyLoggingPreference: DISABLED

Automate private certificate creation

You can use ACM CloudFormation templates to automate the issuance of your private certificates. To perform this action, you need an ACM private certificate authority in order to issue a private certificate. Following is example CloudFormation code for issuing a private ACM certificate. Make sure to replace <region>, the account number, and <certificate_authority_id> with your own data.

Resources:
  ACMPrivateCertificate:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: example3.com
      CertificateAuthorityArn: arn:aws:acm-pca:<region>:111122223333:certificate-authority/<certificate_authority_id>

For more information, see the AWS::CertificateManager::Certificate public documentation.

Summary

We have shown how you can set up AWS CloudFormation templates to issue ACM public and private certificates. When an AWS CloudFormation template is used to issue ACM public certificates and the certificate domain resides in AWS Route 53, the CNAME record for certificate domain validation is automatically created. This helps to reduce the overhead of creating CNAMEs manually.

 
If you have feedback about this post, submit comments in the Comments section below. If you have questions about this post, start a new thread on the AWS Certificate Manager forum or contact AWS Support.