This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

@aws-cdk/aws-certificatemanager

AWS Certificate Manager Construct Library

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

DNS-validated certificates

The DNSValidatedCertificateRequest class provides a Custom Resource by which you can request a TLS certificate from AWS Certificate Manager that is automatically validated using a cryptographically secure DNS record. For this to work, there must be a Route 53 public zone that is responsible for serving records under the Domain Name of the requested certificate. For example, if you request a certificate for www.example.com, there must be a Route 53 public zone example.com that provides authoritative records for the domain.

Example

import { HostedZoneProvider } from '@aws-cdk/aws-route53';
import { DnsValidatedCertificate } from '@aws-cdk/aws-certificatemanager';

const hostedZone = new HostedZoneProvider(this, {
    domainName: 'example.com',
    privateZone: false
}).findAndImport(this, 'ExampleDotCom');

const certificate = new DnsValidatedCertificate(this, 'TestCertificate', {
    domainName: 'test.example.com',
    hostedZone: hostedZone
});

Email validation

Otherwise, if certificates are created as part of a CloudFormation run, the CloudFormation provisioning will not complete until domain ownership for the certificate is completed. For email validation, this involves receiving an email on one of a number of predefined domains and following the instructions in the email. The email addresses use will be:

DNS validation is possible in ACM, but is not currently available in CloudFormation. A Custom Resource will be developed for this, but is not currently available.

Because of these blocks, it’s probably better to provision your certificates either in a separate stack from your main service, or provision them manually. In both cases, you’ll import the certificate into your stack afterwards.

Example

Provision a new certificate by creating an instance of Certificate. Email validation will be sent to example.com:

const certificate = new Certificate(this, 'Certificate', {
    domainName: 'test.example.com'
});

Importing

Import a certificate manually, if you know the ARN:

const certificate = Certificate.import(this, 'Certificate', {
    certificteArn: "arn:aws:..."
});

Sharing between Stacks

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

TODO

  • [ ] Custom Resource that can look up the certificate ARN by domain name by querying ACM.

Reference

View in Nuget

csproj:

<PackageReference Include="Amazon.CDK.AWS.CertificateManager" Version="0.25.3" />

dotnet:

dotnet add package Amazon.CDK.AWS.CertificateManager --version 0.25.3

packages.config:

<package id="Amazon.CDK.AWS.CertificateManager" version="0.25.3" />

View in Maven Central

Apache Buildr:

'software.amazon.awscdk:certificatemanager:jar:0.25.3'

Apache Ivy:

<dependency groupId="software.amazon.awscdk" name="certificatemanager" rev="0.25.3"/>

Apache Maven:

<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>certificatemanager</artifactId>
  <version>0.25.3</version>
</dependency>

Gradle / Grails:

compile 'software.amazon.awscdk:certificatemanager:0.25.3'

Groovy Grape:

@Grapes(
@Grab(group='software.amazon.awscdk', module='certificatemanager', version='0.25.3')
)

View in NPM

npm:

$ npm i @aws-cdk/aws-certificatemanager@0.25.3

package.json:

{
  "@aws-cdk/aws-certificatemanager": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-certificatemanager@0.25.3

View in NPM

npm:

$ npm i @aws-cdk/aws-certificatemanager@0.25.3

package.json:

{
  "@aws-cdk/aws-certificatemanager": "^0.25.3"
}

yarn:

$ yarn add @aws-cdk/aws-certificatemanager@0.25.3

Certificate

class @aws-cdk/aws-certificatemanager.Certificate(scope, id, props)

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.Certificate;
const { Certificate } = require('@aws-cdk/aws-certificatemanager');
import { Certificate } from '@aws-cdk/aws-certificatemanager';

A certificate managed by AWS Certificate Manager

IMPORTANT: if you are creating a certificate as part of your stack, the stack

will not complete creating until you read and follow the instructions in the

email that you will receive.

ACM will send validation emails to the following addresses:

For every domain that you register.

Extends:

@aws-cdk/cdk.Construct

Implements:

ICertificate

Parameters:
static import(scope, id, props) → @aws-cdk/aws-certificatemanager.ICertificate

Import a certificate

Parameters:
Return type:

ICertificate

export() → @aws-cdk/aws-certificatemanager.CertificateImportProps

Implements @aws-cdk/aws-certificatemanager.ICertificate.export()

Export this certificate from the stack

Return type:CertificateImportProps
certificateArn

Implements @aws-cdk/aws-certificatemanager.ICertificate.certificateArn()

The certificate’s ARN

Type:string (readonly)
prepare()

Inherited from @aws-cdk/cdk.Construct

Perform final modifications before synthesis

This method can be implemented by derived constructs in order to perform

final changes before synthesis. prepare() will be called after child

constructs have been prepared.

This is an advanced framework feature. Only use this if you

understand the implications.

Protected method

toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)

CertificateImportProps (interface)

class @aws-cdk/aws-certificatemanager.CertificateImportProps

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.CertificateImportProps;
// CertificateImportProps is an interface
import { CertificateImportProps } from '@aws-cdk/aws-certificatemanager';

Reference to an existing Certificate

certificateArn

The certificate’s ARN

Type:string

CertificateProps (interface)

class @aws-cdk/aws-certificatemanager.CertificateProps

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.CertificateProps;
// CertificateProps is an interface
import { CertificateProps } from '@aws-cdk/aws-certificatemanager';

Properties for your certificate

domainName

Fully-qualified domain name to request a certificate for.

May contain wildcards, such as *.domain.com.

Type:string
subjectAlternativeNames

Alternative domain names on your certificate.

Use this to register alternative domain names that represent the same site.

Type:string[] (optional)
validationDomains

What validation domain to use for every requested domain.

Has to be a superdomain of the requested domain.

Type:string => string (optional)
Default:Apex domain is used for every domain that’s not overridden.

CfnCertificate

class @aws-cdk/aws-certificatemanager.CfnCertificate(scope, id, props)

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.CfnCertificate;
const { CfnCertificate } = require('@aws-cdk/aws-certificatemanager');
import { CfnCertificate } from '@aws-cdk/aws-certificatemanager';
Extends:

@aws-cdk/cdk.Resource

Parameters:
renderProperties(properties) → string => any

Overrides @aws-cdk/cdk.Resource.renderProperties()

Protected method

Parameters:properties (any) –
Return type:string => any
resourceTypeName

The CloudFormation resource type name for this resource class.

Type:string (readonly) (static)
certificateArn
Type:string (readonly)
propertyOverrides
Type:CfnCertificateProps (readonly)
tags

The TagManager handles setting, removing and formatting tags

Tags should be managed either passing them as properties during

initiation or by calling methods on this object. If both techniques are

used only the tags from the TagManager will be used. Tag (aspect)

will use the manager.

Type:@aws-cdk/cdk.TagManager (readonly)
class DomainValidationOptionProperty

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.CfnCertificate.DomainValidationOptionProperty;
// CfnCertificate.DomainValidationOptionProperty is an interface
import { CfnCertificate.DomainValidationOptionProperty } from '@aws-cdk/aws-certificatemanager';
domainName

CfnCertificate.DomainValidationOptionProperty.DomainName

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-certificatemanager-certificate-domainvalidationoption.html#cfn-certificatemanager-certificate-domainvalidationoptions-domainname

Type:string
validationDomain

CfnCertificate.DomainValidationOptionProperty.ValidationDomain

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-certificatemanager-certificate-domainvalidationoption.html#cfn-certificatemanager-certificate-domainvalidationoption-validationdomain

Type:string
toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)
ref

Inherited from @aws-cdk/cdk.Referenceable

Returns a token to a CloudFormation { Ref } that references this entity based on it’s logical ID.

Type:string (readonly)
addDeletionOverride(path)

Inherited from @aws-cdk/cdk.Resource

Syntactic sugar for addOverride(path, undefined).

Parameters:path (string) – The path of the value to delete
addDependsOn(resource)

Inherited from @aws-cdk/cdk.Resource

Indicates that this resource depends on another resource and cannot be provisioned

unless the other resource has been successfully provisioned.

Parameters:resource (@aws-cdk/cdk.Resource) –
addOverride(path, value)

Inherited from @aws-cdk/cdk.Resource

Adds an override to the synthesized CloudFormation resource. To add a

property override, either use addPropertyOverride or prefix path with

“Properties.” (i.e. Properties.TopicName).

Parameters:
  • path (string) – The path of the property, you can use dot notation to override values in complex types. Any intermdediate keys will be created as needed.
  • value (any) – The value. Could be primitive or complex.
addPropertyDeletionOverride(propertyPath)

Inherited from @aws-cdk/cdk.Resource

Adds an override that deletes the value of a property from the resource definition.

Parameters:propertyPath (string) – The path to the property.
addPropertyOverride(propertyPath, value)

Inherited from @aws-cdk/cdk.Resource

Adds an override to a resource property.

Syntactic sugar for addOverride(“Properties.<…>”, value).

Parameters:
  • propertyPath (string) – The path of the property
  • value (any) – The value
getAtt(attributeName) → @aws-cdk/cdk.CfnReference

Inherited from @aws-cdk/cdk.Resource

Returns a token for an runtime attribute of this resource.

Ideally, use generated attribute accessors (e.g. resource.arn), but this can be used for future compatibility

in case there is no generated attribute.

Parameters:attributeName (string) – The name of the attribute.
Return type:@aws-cdk/cdk.CfnReference
toCloudFormation() → json

Inherited from @aws-cdk/cdk.Resource

Emits CloudFormation for this resource.

Return type:json
options

Inherited from @aws-cdk/cdk.Resource

Options for this resource, such as condition, update policy etc.

Type:@aws-cdk/cdk.ResourceOptions (readonly)
properties

Inherited from @aws-cdk/cdk.Resource

AWS resource properties.

This object is rendered via a call to “renderProperties(this.properties)”.

Protected property

Type:any (readonly)
resourceType

Inherited from @aws-cdk/cdk.Resource

AWS resource type.

Type:string (readonly)
untypedPropertyOverrides

Inherited from @aws-cdk/cdk.Resource

AWS resource property overrides.

During synthesis, the method “renderProperties(this.overrides)” is called

with this object, and merged on top of the output of

“renderProperties(this.properties)”.

Derived classes should expose a strongly-typed version of this object as

a public property called propertyOverrides.

Protected property

Type:any (readonly)
overrideLogicalId(newLogicalId)

Inherited from @aws-cdk/cdk.StackElement

Overrides the auto-generated logical ID with a specific ID.

Parameters:newLogicalId (string) – The new logical ID to use for this stack element.
prepare()

Inherited from @aws-cdk/cdk.StackElement

Automatically detect references in this StackElement

Protected method

creationStackTrace

Inherited from @aws-cdk/cdk.StackElement

Type:string[] (readonly)
logicalId

Inherited from @aws-cdk/cdk.StackElement

The logical ID for this CloudFormation stack element. The logical ID of the element

is calculated from the path of the resource node in the construct tree.

To override this value, use overrideLogicalId(newLogicalId).

Type:string (readonly)
stackPath

Inherited from @aws-cdk/cdk.StackElement

Return the path with respect to the stack

Type:string (readonly)

CfnCertificateProps (interface)

class @aws-cdk/aws-certificatemanager.CfnCertificateProps

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.CfnCertificateProps;
// CfnCertificateProps is an interface
import { CfnCertificateProps } from '@aws-cdk/aws-certificatemanager';
domainName

AWS::CertificateManager::Certificate.DomainName

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-certificatemanager-certificate.html#cfn-certificatemanager-certificate-domainname

Type:string
domainValidationOptions

AWS::CertificateManager::Certificate.DomainValidationOptions

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-certificatemanager-certificate.html#cfn-certificatemanager-certificate-domainvalidationoptions

Type:@aws-cdk/cdk.Token or (DomainValidationOptionProperty or @aws-cdk/cdk.Token)[] (optional)
subjectAlternativeNames

AWS::CertificateManager::Certificate.SubjectAlternativeNames

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-certificatemanager-certificate.html#cfn-certificatemanager-certificate-subjectalternativenames

Type:@aws-cdk/cdk.Token or (string or @aws-cdk/cdk.Token)[] (optional)
tags

AWS::CertificateManager::Certificate.Tags

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-certificatemanager-certificate.html#cfn-certificatemanager-certificate-tags

Type:@aws-cdk/cdk.Token or (@aws-cdk/cdk.Token or @aws-cdk/cdk.CfnTag)[] (optional)
validationMethod

AWS::CertificateManager::Certificate.ValidationMethod

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-certificatemanager-certificate.html#cfn-certificatemanager-certificate-validationmethod

Type:string (optional)

DnsValidatedCertificate

class @aws-cdk/aws-certificatemanager.DnsValidatedCertificate(scope, id, props)

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.DnsValidatedCertificate;
const { DnsValidatedCertificate } = require('@aws-cdk/aws-certificatemanager');
import { DnsValidatedCertificate } from '@aws-cdk/aws-certificatemanager';

A certificate managed by AWS Certificate Manager. Will be automatically

validated using DNS validation against the specified Route 53 hosted zone.

Extends:

@aws-cdk/cdk.Construct

Implements:

ICertificate

Parameters:
export() → @aws-cdk/aws-certificatemanager.CertificateImportProps

Implements @aws-cdk/aws-certificatemanager.ICertificate.export()

Export this certificate from the stack

Return type:CertificateImportProps
validate() → string[]

Overrides @aws-cdk/cdk.Construct.validate()

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Return type:string[]
certificateArn

Implements @aws-cdk/aws-certificatemanager.ICertificate.certificateArn()

The certificate’s ARN

Type:string (readonly)
prepare()

Inherited from @aws-cdk/cdk.Construct

Perform final modifications before synthesis

This method can be implemented by derived constructs in order to perform

final changes before synthesis. prepare() will be called after child

constructs have been prepared.

This is an advanced framework feature. Only use this if you

understand the implications.

Protected method

toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
dependencyRoots

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)
node

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)

DnsValidatedCertificateProps (interface)

class @aws-cdk/aws-certificatemanager.DnsValidatedCertificateProps

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.DnsValidatedCertificateProps;
// DnsValidatedCertificateProps is an interface
import { DnsValidatedCertificateProps } from '@aws-cdk/aws-certificatemanager';
Extends:CertificateProps
hostedZone

Route 53 Hosted Zone used to perform DNS validation of the request. The zone

must be authoritative for the domain name specified in the Certificate Request.

Type:@aws-cdk/aws-route53.IHostedZone
domainName

Inherited from @aws-cdk/aws-certificatemanager.CertificateProps

Fully-qualified domain name to request a certificate for.

May contain wildcards, such as *.domain.com.

Type:string
subjectAlternativeNames

Inherited from @aws-cdk/aws-certificatemanager.CertificateProps

Alternative domain names on your certificate.

Use this to register alternative domain names that represent the same site.

Type:string[] (optional)
validationDomains

Inherited from @aws-cdk/aws-certificatemanager.CertificateProps

What validation domain to use for every requested domain.

Has to be a superdomain of the requested domain.

Type:string => string (optional)
Default:Apex domain is used for every domain that’s not overridden.

ICertificate (interface)

class @aws-cdk/aws-certificatemanager.ICertificate

Language-specific names:

using Amazon.CDK.AWS.CertificateManager;
import software.amazon.awscdk.services.certificatemanager.ICertificate;
// ICertificate is an interface
import { ICertificate } from '@aws-cdk/aws-certificatemanager';
Extends:@aws-cdk/cdk.IConstruct
certificateArn

The certificate’s ARN

Type:string (readonly)
export() → @aws-cdk/aws-certificatemanager.CertificateImportProps

Export this certificate from the stack

Return type:CertificateImportProps
Abstract:Yes
node

Inherited from @aws-cdk/cdk.IConstruct

The construct node in the scope tree.

Type:@aws-cdk/cdk.ConstructNode (readonly)
dependencyRoots

Inherited from @aws-cdk/cdk.IDependable

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering

dependency.

Type:@aws-cdk/cdk.IConstruct[] (readonly)