Namespace Amazon.CDK.AWS.CertificateManager

AWS Certificate Manager Construct Library

AWS Certificate Manager (ACM) handles the complexity of creating, storing, and renewing public and private SSL/TLS X.509 certificates and keys that protect your AWS websites and applications. ACM certificates can secure singular domain names, multiple specific domain names, wildcard domains, or combinations of these. ACM wildcard certificates can protect an unlimited number of subdomains.

This package provides Constructs for provisioning and referencing ACM certificates which can be used with CloudFront and ELB.

After requesting a certificate, you will need to prove that you own the domain in question before the certificate will be granted. The CloudFormation deployment will wait until this verification process has been completed.

Because of this wait time, when using manual validation methods, it's better to provision your certificates either in a separate stack from your main service, or provision them manually and import them into your CDK application.

Note: There is a limit on total number of ACM certificates that can be requested on an account and region within a year. The default limit is 2000, but this limit may be (much) lower on new AWS accounts. See https://docs.aws.amazon.com/acm/latest/userguide/acm-limits.html for more information.

DNS validation

DNS validation is the preferred method to validate domain ownership, as it has a number of advantages over email validation. See also Validate with DNS in the AWS Certificate Manager User Guide.

If Amazon Route 53 is your DNS provider for the requested domain, the DNS record can be created automatically:

var myHostedZone = new HostedZone(this, "HostedZone", new HostedZoneProps {
    ZoneName = "example.com"
});
new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "hello.example.com",
    CertificateName = "Hello World Service",  // Optionally provide an certificate name
    Validation = CertificateValidation.FromDns(myHostedZone)
});

If Route 53 is not your DNS provider, the DNS records must be added manually and the stack will not complete creating until the records are added.

new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "hello.example.com",
    Validation = CertificateValidation.FromDns()
});

When working with multiple domains, use the CertificateValidation.fromDnsMultiZone():

var exampleCom = new HostedZone(this, "ExampleCom", new HostedZoneProps {
    ZoneName = "example.com"
});
var exampleNet = new HostedZone(this, "ExampleNet", new HostedZoneProps {
    ZoneName = "example.net"
});

var cert = new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "test.example.com",
    SubjectAlternativeNames = new [] { "cool.example.com", "test.example.net" },
    Validation = CertificateValidation.FromDnsMultiZone(new Dictionary<string, IHostedZone> {
        { "test.example.com", exampleCom },
        { "cool.example.com", exampleCom },
        { "test.example.net", exampleNet }
    })
});

Email validation

Email-validated certificates (the default) are validated by receiving an email on one of a number of predefined domains and following the instructions in the email.

See Validate with Email in the AWS Certificate Manager User Guide.

new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "hello.example.com",
    Validation = CertificateValidation.FromEmail()
});

Cross-region Certificates

ACM certificates that are used with CloudFront -- or higher-level constructs which rely on CloudFront -- must be in the us-east-1 region. CloudFormation allows you to create a Stack with a CloudFront distribution in any region. In order to create an ACM certificate in us-east-1 and reference it in a CloudFront distribution is a different region, it is recommended to perform a multi stack deployment.

Enable the Stack property crossRegionReferences in order to access the cross stack/region certificate.

This feature is currently experimental

using Amazon.CDK.AWS.CloudFront;
using Amazon.CDK.AWS.CloudFront.Origins;
App app;


var stack1 = new Stack(app, "Stack1", new StackProps {
    Env = new Environment {
        Region = "us-east-1"
    },
    CrossRegionReferences = true
});
var cert = new Certificate(stack1, "Cert", new CertificateProps {
    DomainName = "*.example.com",
    Validation = CertificateValidation.FromDns(PublicHostedZone.FromHostedZoneId(stack1, "Zone", "ZONE_ID"))
});

var stack2 = new Stack(app, "Stack2", new StackProps {
    Env = new Environment {
        Region = "us-east-2"
    },
    CrossRegionReferences = true
});

new Distribution(stack2, "Distribution", new DistributionProps {
    DefaultBehavior = new BehaviorOptions {
        Origin = new HttpOrigin("example.com")
    },
    DomainNames = new [] { "dev.example.com" },
    Certificate = cert
});

Requesting private certificates

AWS Certificate Manager can create private certificates issued by Private Certificate Authority (PCA). Validation of private certificates is not necessary.

using Amazon.CDK.AWS.ACMPCA;


new PrivateCertificate(this, "PrivateCertificate", new PrivateCertificateProps {
    DomainName = "test.example.com",
    SubjectAlternativeNames = new [] { "cool.example.com", "test.example.net" },  // optional
    CertificateAuthority = CertificateAuthority.FromCertificateAuthorityArn(this, "CA", "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/023077d8-2bfa-4eb0-8f22-05c96deade77"),
    KeyAlgorithm = KeyAlgorithm.RSA_2048
});

Requesting certificates without transparency logging

Transparency logging can be opted out of for AWS Certificate Manager certificates. See opting out of certificate transparency logging for limits.

new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "test.example.com",
    TransparencyLoggingEnabled = false
});

Key Algorithms

To specify the algorithm of the public and private key pair that your certificate uses to encrypt data use the keyAlgorithm property.

Algorithms supported for an ACM certificate request include:

new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "test.example.com",
    KeyAlgorithm = KeyAlgorithm.EC_PRIME256V1
});

Visit <a href="https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate.html#algorithms.title">Key algorithms</a> for more details.

Importing

If you want to import an existing certificate, you can do so from its ARN:

var arn = "arn:aws:...";
var certificate = Certificate.FromCertificateArn(this, "Certificate", arn);

Sharing between Stacks

To share the certificate between stacks in the same CDK application, simply pass the Certificate object between the stacks.

Metrics

The DaysToExpiry metric is available via the metricDaysToExpiry method for all certificates. This metric is emitted by AWS Certificates Manager once per day until the certificate has effectively expired.

An alarm can be created to determine whether a certificate is soon due for renewal ussing the following code:

using Amazon.CDK.AWS.CloudWatch;

HostedZone myHostedZone;

var certificate = new Certificate(this, "Certificate", new CertificateProps {
    DomainName = "hello.example.com",
    Validation = CertificateValidation.FromDns(myHostedZone)
});
certificate.MetricDaysToExpiry().CreateAlarm(this, "Alarm", new CreateAlarmOptions {
    ComparisonOperator = ComparisonOperator.LESS_THAN_THRESHOLD,
    EvaluationPeriods = 1,
    Threshold = 45
});

Classes

Certificate	A certificate managed by AWS Certificate Manager.
CertificateProps	Properties for your certificate.
CertificateValidation	How to validate a certificate.
CertificationValidationProps	Properties for certificate validation.
CfnAccount	The `AWS::CertificateManager::Account` resource defines the expiry event configuration that determines the number of days prior to expiry when ACM starts generating EventBridge events.
CfnAccount.ExpiryEventsConfigurationProperty	Object containing expiration events options associated with an AWS account .
CfnAccountProps	Properties for defining a `CfnAccount`.
CfnCertificate	The `AWS::CertificateManager::Certificate` resource requests an AWS Certificate Manager ( ACM ) certificate that you can use to enable secure connections.
CfnCertificate.DomainValidationOptionProperty	`DomainValidationOption` is a property of the AWS::CertificateManager::Certificate resource that specifies the AWS Certificate Manager ( ACM ) certificate domain to validate. Depending on the chosen validation method, ACM checks the domain's DNS record for a validation CNAME, or it attempts to send a validation email message to the domain owner.
CfnCertificateProps	Properties for defining a `CfnCertificate`.
DnsValidatedCertificate	(deprecated) A certificate managed by AWS Certificate Manager.
DnsValidatedCertificateProps	Properties to create a DNS validated certificate managed by AWS Certificate Manager.
KeyAlgorithm	Certificate Manager key algorithm.
PrivateCertificate	A private certificate managed by AWS Certificate Manager.
PrivateCertificateProps	Properties for your private certificate.
ValidationMethod	Method used to assert ownership of the domain.

Interfaces

CfnAccount.IExpiryEventsConfigurationProperty	Object containing expiration events options associated with an AWS account .
CfnCertificate.IDomainValidationOptionProperty	`DomainValidationOption` is a property of the AWS::CertificateManager::Certificate resource that specifies the AWS Certificate Manager ( ACM ) certificate domain to validate. Depending on the chosen validation method, ACM checks the domain's DNS record for a validation CNAME, or it attempts to send a validation email message to the domain owner.
ICertificate	Represents a certificate in AWS Certificate Manager.
ICertificateProps	Properties for your certificate.
ICertificationValidationProps	Properties for certificate validation.
ICfnAccountProps	Properties for defining a `CfnAccount`.
ICfnCertificateProps	Properties for defining a `CfnCertificate`.
IDnsValidatedCertificateProps	Properties to create a DNS validated certificate managed by AWS Certificate Manager.
IPrivateCertificateProps	Properties for your private certificate.