1 | # AWS Certificate Manager Construct Library
|
2 |
|
3 |
|
4 | ---
|
5 |
|
6 | ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
|
7 |
|
8 | ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
|
9 |
|
10 | ---
|
11 |
|
12 |
|
13 |
|
14 |
|
15 | AWS Certificate Manager (ACM) handles the complexity of creating, storing, and renewing public and private SSL/TLS X.509 certificates and keys that
|
16 | protect your AWS websites and applications. ACM certificates can secure singular domain names, multiple specific domain names, wildcard domains, or
|
17 | combinations of these. ACM wildcard certificates can protect an unlimited number of subdomains.
|
18 |
|
19 | This package provides Constructs for provisioning and referencing ACM certificates which can be used with CloudFront and ELB.
|
20 |
|
21 | After requesting a certificate, you will need to prove that you own the
|
22 | domain in question before the certificate will be granted. The CloudFormation
|
23 | deployment will wait until this verification process has been completed.
|
24 |
|
25 | Because of this wait time, when using manual validation methods, it's better
|
26 | to provision your certificates either in a separate stack from your main
|
27 | service, or provision them manually and import them into your CDK application.
|
28 |
|
29 | **Note:** There is a limit on total number of ACM certificates that can be requested on an account and region within a year.
|
30 | The default limit is 2000, but this limit may be (much) lower on new AWS accounts.
|
31 | See https://docs.aws.amazon.com/acm/latest/userguide/acm-limits.html for more information.
|
32 |
|
33 | ## DNS validation
|
34 |
|
35 | DNS validation is the preferred method to validate domain ownership, as it has a number of advantages over email validation.
|
36 | See also [Validate with DNS](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html)
|
37 | in the AWS Certificate Manager User Guide.
|
38 |
|
39 | If Amazon Route 53 is your DNS provider for the requested domain, the DNS record can be
|
40 | created automatically:
|
41 |
|
42 | ```ts
|
43 | const myHostedZone = new route53.HostedZone(this, 'HostedZone', {
|
44 | zoneName: 'example.com',
|
45 | });
|
46 | new acm.Certificate(this, 'Certificate', {
|
47 | domainName: 'hello.example.com',
|
48 | validation: acm.CertificateValidation.fromDns(myHostedZone),
|
49 | });
|
50 | ```
|
51 |
|
52 | If Route 53 is not your DNS provider, the DNS records must be added manually and the stack will not complete
|
53 | creating until the records are added.
|
54 |
|
55 | ```ts
|
56 | new acm.Certificate(this, 'Certificate', {
|
57 | domainName: 'hello.example.com',
|
58 | validation: acm.CertificateValidation.fromDns(), // Records must be added manually
|
59 | });
|
60 | ```
|
61 |
|
62 | When working with multiple domains, use the `CertificateValidation.fromDnsMultiZone()`:
|
63 |
|
64 | ```ts
|
65 | const exampleCom = new route53.HostedZone(this, 'ExampleCom', {
|
66 | zoneName: 'example.com',
|
67 | });
|
68 | const exampleNet = new route53.HostedZone(this, 'ExampleNet', {
|
69 | zoneName: 'example.net',
|
70 | });
|
71 |
|
72 | const cert = new acm.Certificate(this, 'Certificate', {
|
73 | domainName: 'test.example.com',
|
74 | subjectAlternativeNames: ['cool.example.com', 'test.example.net'],
|
75 | validation: acm.CertificateValidation.fromDnsMultiZone({
|
76 | 'test.example.com': exampleCom,
|
77 | 'cool.example.com': exampleCom,
|
78 | 'test.example.net': exampleNet,
|
79 | }),
|
80 | });
|
81 | ```
|
82 |
|
83 | ## Email validation
|
84 |
|
85 | Email-validated certificates (the default) are validated by receiving an
|
86 | email on one of a number of predefined domains and following the instructions
|
87 | in the email.
|
88 |
|
89 | See [Validate with Email](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-email.html)
|
90 | in the AWS Certificate Manager User Guide.
|
91 |
|
92 | ```ts
|
93 | new acm.Certificate(this, 'Certificate', {
|
94 | domainName: 'hello.example.com',
|
95 | validation: acm.CertificateValidation.fromEmail(), // Optional, this is the default
|
96 | });
|
97 | ```
|
98 |
|
99 | ## Cross-region Certificates
|
100 |
|
101 | ACM certificates that are used with CloudFront -- or higher-level constructs which rely on CloudFront -- must be in the `us-east-1` region.
|
102 | The `DnsValidatedCertificate` construct exists to facilitate creating these certificates cross-region. This resource can only be used with
|
103 | Route53-based DNS validation.
|
104 |
|
105 | ```ts
|
106 | declare const myHostedZone: route53.HostedZone;
|
107 | new acm.DnsValidatedCertificate(this, 'CrossRegionCertificate', {
|
108 | domainName: 'hello.example.com',
|
109 | hostedZone: myHostedZone,
|
110 | region: 'us-east-1',
|
111 | });
|
112 | ```
|
113 |
|
114 | ## Requesting private certificates
|
115 |
|
116 | AWS Certificate Manager can create [private certificates](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-private.html) issued by [Private Certificate Authority (PCA)](https://docs.aws.amazon.com/acm-pca/latest/userguide/PcaWelcome.html). Validation of private certificates is not necessary.
|
117 |
|
118 | ```ts
|
119 | import * as acmpca from '@aws-cdk/aws-acmpca';
|
120 |
|
121 | new acm.PrivateCertificate(this, 'PrivateCertificate', {
|
122 | domainName: 'test.example.com',
|
123 | subjectAlternativeNames: ['cool.example.com', 'test.example.net'], // optional
|
124 | certificateAuthority: acmpca.CertificateAuthority.fromCertificateAuthorityArn(this, 'CA',
|
125 | 'arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/023077d8-2bfa-4eb0-8f22-05c96deade77'),
|
126 | });
|
127 | ```
|
128 |
|
129 | ## Importing
|
130 |
|
131 | If you want to import an existing certificate, you can do so from its ARN:
|
132 |
|
133 | ```ts
|
134 | const arn = 'arn:aws:...';
|
135 | const certificate = acm.Certificate.fromCertificateArn(this, 'Certificate', arn);
|
136 | ```
|
137 |
|
138 | ## Sharing between Stacks
|
139 |
|
140 | To share the certificate between stacks in the same CDK application, simply
|
141 | pass the `Certificate` object between the stacks.
|
142 |
|
143 | ## Metrics
|
144 |
|
145 | The `DaysToExpiry` metric is available via the `metricDaysToExpiry` method for
|
146 | all certificates. This metric is emitted by AWS Certificates Manager once per
|
147 | day until the certificate has effectively expired.
|
148 |
|
149 | An alarm can be created to determine whether a certificate is soon due for
|
150 | renewal ussing the following code:
|
151 |
|
152 | ```ts
|
153 | import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
|
154 |
|
155 | declare const myHostedZone: route53.HostedZone;
|
156 | const certificate = new acm.Certificate(this, 'Certificate', {
|
157 | domainName: 'hello.example.com',
|
158 | validation: acm.CertificateValidation.fromDns(myHostedZone),
|
159 | });
|
160 | certificate.metricDaysToExpiry().createAlarm(this, 'Alarm', {
|
161 | comparisonOperator: cloudwatch.ComparisonOperator.LESS_THAN_THRESHOLD,
|
162 | evaluationPeriods: 1,
|
163 | threshold: 45, // Automatic rotation happens between 60 and 45 days before expiry
|
164 | });
|
165 | ```
|