Let’s Encrypt DNS01 Challenge with Route53 Feature on Convox

Hello there, Convox community! We have some exciting news for you. We’ve now integrated support for the Let’s Encrypt DNS01 challenge using AWS Route53, which means you now have more flexibility with your SSL and the ability to issue wildcard certificates. In this blog we will go over some general information and walk through the setup process.

What is the Let’s Encrypt DNS01 Challenge?

In brief, the DNS01 challenge allows domain validation by proving you control the DNS for your domain. This is done by creating a specific DNS TXT record. Once the record is verified, the certificate is issued.

How does this differ from the default HTTP-01 challenge?

While the HTTP-01 challenge validates domain ownership by asking users to place a specific file at a known path on the website, the DNS01 challenge proves ownership through a DNS TXT record. The DNS01 challenge is particularly beneficial when you can’t or don’t wish to expose an HTTP endpoint to the world, such as in more secure or complex network environments.

What advantages does the DNS01 challenge offer?

The DNS01 challenge has a few distinct advantages. First, it can be used to issue wildcard certificates, allowing a single certificate to secure multiple subdomains of a domain (e.g., *.yourdomain.com). Wildcard certificates simplify certificate management and can be particularly cost-effective. Additionally, because the DNS01 challenge doesn’t require exposing an HTTP endpoint, it can be a preferred method for networks with stringent security requirements or when the application infrastructure is complex.

Pre-Check

It is important to make sure there are no outdated certificate management objects.

Please make sure you’re set to your kubeconfig to the rack’s context by running

convox rack kubeconfig > ~/.kube/config

And then running the following script:

    #!/bin/bash
for kind in challenges certificaterequests certificates clusterissuers orders issuers; do
    kubectl explain $kind | grep -e "KIND:" -e "VERSION:"
done

All of your objects should show v1. If not, please contact Convox support before attempting to enable DNS01 challenge.

Setting Up Let’s Encrypt DNS01 Challenge with Route53:

1. Retrieve the IAM Role Used By The Service:

Start by retrieving the IAM role that is used by the service:

$ convox  letsencrypt  dns route53 role
arn:aws:iam::  XXXXXXXXXX:role/convox/rackName-cert-manager

2. Create a Route53 DNS Zone Access Role:

Now you need to create a new role in AWS IAM with specific permissions. Use the following policy for permissions and remember to replace with your actual zone id from Route 53:

{ 
    "Version": "2012-10-17", 
    "Statement": [ 
        { 
            "Effect": "Allow", 
            "Action": "route53:GetChange", 
            "Resource": [ 
                "arn:aws:route53:::change/*" 
            ] 
        }, 
        { 
            "Effect": "Allow", 
            "Action": [ 
                "route53:ChangeResourceRecordSets", 
                "route53:ListResourceRecordSets" 
            ], 
            "Resource": [ 
                "arn:aws:route53:::hostedzone/<zone-id>" 
            ] 
        } 
    ] 
} 

3. Update the Route 53 DNS Access Role’s Trust Policy:

You need to give the rackName-cert-manager role permission to assume the newly created Route 53 DNS access role by adding the following Trust Policy to the role in AWS IAM:

{ 
    "Version": "2012-10-17", 
    "Statement": [ 
        { 
            "Sid": "", 
            "Effect": "Allow", 
            "Principal": { 
                "AWS": [ 
                    "arn:aws:iam::XXXXXXXXXX:role/convox/rackName-cert-manager" 
                ] 
            }, 
            "Action": "sts:AssumeRole" 
        } 
    ] 
} 

4. Add Assume Permission Policy to cert-manager Role:

Add the following permission policy to your rackName-cert-manager role so that it can assume the newly created :

{ 
	"Version": "2012-10-17", 
	"Statement": [ 
		{ 
			"Sid": "Statement1", 
			"Effect": "Allow", 
			"Action": [ 
				"sts:AssumeRole" 
				], 
	"Resource": [ 
	"arn:aws:iam::XXXXXXXXXX:role/dns-access" 
			] 
		} 
	] 
} 

5. Configure DNS Solver for Let’s Encrypt:

Use the following command, and ensure you replace the placeholders with your specific values:

$ convox  letsencrypt  dns route53 add --id 1 --dns-zones your.zone  --role arn:aws:iam::XXXXXX:role/dns-access --hosted-zone-id xxxxxxx

Check the Configuration:

Verify that everything is configured correctly:

$ convox  letsencrypt  dns route53 list
ID DNS-ZONES HOSTED-ZONE-ID REGION ROLE
1 your.zone XXXXXXXXXXXXX us-east-1 arn:aws:iam::XXXXXXXXXXXXXXX:role/dns-access

With these steps completed, Let’s Encrypt will leverage the DNS01 challenge to issue a certificate for your domain using the Route 53 hosted zone you specify.

In summary, the DNS01 challenge offers a distinct path for domain validation, especially useful for those looking to issue wildcard certificates. While our default recommendation remains the HTTP-01 challenge for its simplicity, this new addition provides an alternative for specific use cases and network configurations.

We appreciate your continuous engagement with Convox and look forward to supporting your diverse application requirements. Happy coding!