Recently, Amazon announced free SSL certs via AWS Certificate Manager, or ACM. This week, we’ll use CloudFormation to provision ACM certificates automatically. I built my own custom ACM resource in Python. With this resource, you can configure a CloudFront distribution for your static content and get a custom SSL for your domain.
In this post, we’ll use custom resources to issue an ACM certificate, then associate that certificate to a CloudFront distribution.
Issuing a Certificate
We’ll start with the template from this post that already
issues SSL certificates with ACM and build up from there. For an more about
that template, go to the post on making custom resources or
launch it
.
It already creates the function and ACM certificate custom
resource like so:
"AcmCertificate": {
"Type": "Custom::AcmCertificate",
"Properties": {
"Domains": {
"Ref": "Domains"
},
"ServiceToken": {
"Fn::GetAtt": [
"AcmRegistrationFunction",
"Arn"
]
},
"Await": true
}
}
We’ll have to add a CloudFront distribution, for testing we’ll just point it at the S3 bucket for my personal website. Of course, you’ll want to substitute in your own origin.
"SiteCDN": {
"Type": "AWS::CloudFront::Distribution",
"Description": "CDN for site content",
"Properties": {
"DistributionConfig": {
"DefaultCacheBehavior": {
"ViewerProtocolPolicy": "allow-all",
"ForwardedValues": {
"QueryString": true
},
"TargetOriginId": "static-site-origin",
"MinTTL": 300
},
"Origins": [
{
"DomainName": "rsb.io.s3-website-us-east-1.amazonaws.com",
"Id": "static-site-origin",
"CustomOriginConfig": {
"OriginProtocolPolicy": "http-only",
"HTTPPort": 80,
"HTTPSPort": 443
}
}
],
"PriceClass": "PriceClass_100",
"DefaultRootObject": "index.html",
"Enabled": true,
"Aliases": {
"Ref": "Domains"
}
}
}
}
You’ll notice that this resource doesn’t make use of the ACM certificate. The
reason it can’t is because the CloudFormation resource only allows IAM
certificates even though ACM certificates are available in the CloudFront API.
To get around this, I built the Custom::CloudFrontAcmAssociation resource
that takes a distribution and an ACM certificate and sets it up with
CloudFront.
We can associate the two like so:
"DistributionCertificateSetting": {
"Type": "Custom::CloudFrontAcmAssociation",
"Properties": {
"DistributionId": {
"Ref": "SiteCDN"
},
"CertificateArn": {
"Ref": "AcmCertificate"
},
"ServiceToken": {
"Fn::GetAtt": [
"AcmAssociationFunction",
"Arn"
]
}
}
},
To launch this stack, click here:
Launching the stack will take some time - it can take up to 30 minutes for the CloudFront distribution to be created. You should receive an email to your domain administration email asking you to confirm the certificate, click through that as soon as possible. The full template is available here if you want to review it.
What’s Under the Hood
While we’re waiting, let’s look at how these resources work. The code for all
these resources is on Github at ryansb/acm-certs-cloudformation. For issuing ACM certificates, we need a CREATE method that takes the
parameters we specified earlier.
@handler.create
def create_cert(event, context):
# get the properties set in the CloudFormation resource
props = event['ResourceProperties']
domains = props['Domains'] # list of domain names
# take a hash of the Stack & resource ID to make a request token
id_token = hashlib.md5('cfn-{StackId}-{LogicalResourceId}'.format(
**event)).hexdigest()
This part of the code is what generates the IdempotencyToken needed by the
ACM API to deduplicate requests. This token is unique per
stack/resource combination, so if for some reason the request is sent twice for
the same resource, two certificates aren’t issued.
To make the token unique, we take the hash of the (globally unique) Stack ID and the (unique within a stack) logical ID of the resource. This way we know for a fact that there won’t be duplicates.
kwargs = {
'DomainName': domains[0],
# the idempotency token length limit is 31 characters
'IdempotencyToken': id_token[:30]
}
if len(domains) > 1:
# add alternative names if the user wants more names
# wildcards are allowed
kwargs['SubjectAlternativeNames'] = domains[1:]
if props.get('ValidationOptions'):
""" List of domain validation options. Looks like:
{
"DomainName": "test.foo.com",
"ValidationDomain": "foo.com",
}
"""
kwargs['DomainValidationOptions'] = props.get('ValidationOptions')
# here we actually make the request
response = acm.request_certificate(**kwargs)
if props.get('Await', False):
await_validation(domains[0], context)
return {
'Status': 'SUCCESS',
'Reason': 'Cert request created successfully',
'PhysicalResourceId': response['CertificateArn'],
'Data': {},
}
Full code here
With that, we’ve succeeded in creating a request for a certificate. To wait for
it, we’ll need to add an await_validation method that checks to see if the
certificate is issued.
def await_validation(domain, context):
# as long as we have at least 10 seconds left
while context.get_remaining_time_in_millis() > 10000:
time.sleep(5)
resp = acm.list_certificates(CertificateStatuses=['ISSUED'])
if any(cert['DomainName'] == domain for cert in resp['CertificateSummaryList']):
cert_info = [cert for cert in resp['CertificateSummaryList']
if cert['DomainName'] == domain][0]
log.info("Certificate has been issued for domain %s, ARN: %s" %
(domain, cert_info['CertificateArn']))
return cert_info['CertificateArn']
log.info("Awaiting cert for domain %s" % domain)
log.warning("Timed out waiting for cert for domain %s" % domain)
This method uses the context object to see how much execution time
we have left. If there’s still time, it will wait a bit and check if the
certificate is ready yet. We only use this method if the user set "Await": true, otherwise we just issue the request for the certificate and return
SUCCESS.
Deletion is even simpler, because there’s nothing to check. When creating the
certificate we tell CloudFormation the ARN of the certificate, and it sends it
with the DELETE request. We just need to use the PhysicalResourceId where
the ARN is saved to delete the certificate.
@handler.delete
def delete_certificate(event, context):
resp = {'Status': 'SUCCESS',
'PhysicalResourceId': event['PhysicalResourceId'],
'Data': {},
}
try:
acm.delete_certificate(CertificateArn=event['PhysicalResourceId'])
except:
log.exception('Failure deleting cert with arn %s' % event['PhysicalResourceId'])
resp['Reason'] = 'Some exception was raised while deleting the cert'
return resp
That’s about it for the Python to handle the creating/deleting ACM certificates. What about associating them with CloudFront distributions?
def create_cert_association(event, context):
props = event['ResourceProperties']
cert_arn = props['CertificateArn']
dist_id = props['DistributionId']
response = cloudfront.get_distribution_config(Id=dist_id)
config = response['DistributionConfig']
# we need to send the ETag of the configuration back with our change
# request to make sure there isn't a config change we missed
etag = response['ETag']
reason = ''
if config.get('ViewerCertificate') is None:
return {
'Status': 'FAILED',
'Reason': 'No viewercert configuration',
'Data': {}
}
elif config['ViewerCertificate'].get('CertificateSource', '') == 'acm':
if config['ViewerCertificate']['Certificate'] == cert_arn:
log.debug('Already configured - nothing to do')
reason = 'Already connected, easy!'
else:
associate_cert(cert_arn, dist_id, config, etag)
reason = 'Changed ACM cert ID'
else:
associate_cert(cert_arn, dist_id, config, etag)
reason = 'Associated ACM cert'
return {
'Status': 'SUCCESS',
'Reason': reason,
'PhysicalResourceId': generate_phys_id(cert_arn, dist_id),
'Data': {},
}
Full code is here
Now that we’ve seen how the associations work, and how the cert is issued, let’s check back in the CloudFormation console to see if the stack is done yet.
Wrapping Up
Now we need to check if the certificate works. If you don’t want to set your
DNS to point to CloudFront, you can use the --resolve option with curl to
fake it locally for testing.
$ curl -v -s --resolve yourdomain.com:443:$(dig +short A [cloudfront name] | head -n1) https://yourdomain.com >/dev/null
You’ll need to fill in [cloudfront name] to be the DNS name of the CloudFront
distribution. you can get this from the CloudFront web console. For me (using
serverlesscode.com), the output looks like this:
* Trying 52.84.29.120...
* Connected to serverlesscode.com (52.84.29.120) port 443 (#0)
* Initializing NSS with certpath: sql:/etc/pki/nssdb
* CAfile: /etc/pki/tls/certs/ca-bundle.crt
CApath: none
* SSL connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate:
* subject: CN=serverlesscode.com
* start date: Jan 21 00:00:00 2016 GMT
* expire date: Feb 21 12:00:00 2017 GMT
* common name: serverlesscode.com
* issuer: CN=Amazon,OU=Server CA 1B,O=Amazon,C=US
As you can see, the certificate is the Amazon-issued ACM cert, and is accepted by just about every OS. Congratulations! Now you’re set up with free SSL and a great CDN, all from one CloudFormation stack.
Keep up with future posts via RSS. If you have suggestions, questions, or comments my email is ryan@serverlesscode.com.