Use IBM Cloud Certificate Manager to Obtain Let's Encrypt TLS Certificates for Your Public Domains
By: Arik Shifer and Carmel Schindelhaim
IBM Cloud Certificate Manager now lets you order TLS certificates
To enable HTTPS on your public domains, you need to obtain a TLS certificate from a Certificate Authority (CA). The CA acts as a trusted third party for both the requester of the certificate, and the client that relies on the certificate.
IBM Cloud Certificate Manager now lets you obtain TLS certificates signed by Let’s Encrypt. Let’s Encrypt is an automated, ACME-protocol-based CA that issues free certificates valid for 90 days. Certificate Manager also helps you manage the lifecycle of your certificates and keep them secure.
When you order a certificate, you have to demonstrate that you control the domain you are requesting the certificate for. In this blog, we explain how you can prove that you control this domain automatically, so that you can get a certificate issued to you within minutes.
Automatically demonstrating control of your domain
Domain validation works in the following way:
- You request a certificate for a domain or set of domains through Certificate Manager.
- Certificate Manager will send you a challenge in the form of a TXT record that you have to add to your Domain Name System (DNS) records.
- Certificate Manager will check to see that you've added the TXT records for those domains.
- If you've added these successfully, you'll get a new certificate in Certificate Manager.
In order for this process to be automated, Certificate Manager will send you the TXT record to your callback URL using the Certificate Manager notifications mechanism. The code you have running that receives this notification can update your DNS service, provided that your DNS provider has a public API for adding and removing DNS TXT records. You will receive a separate DNS TXT challenge for each domain that you request.
Setting things up
First, identify your DNS provider for your domains, and make sure it has APIs for adding and removing DNS TXT records.
Next, you'll need to implement an endpoint that will receive the notification message containing the domain validation challenge from Certificate Manager, and fulfill the challenge by adding the TXT record to the domain record in your DNS.
Here is a code example for implementing a domain validation endpoint using an IBM Cloud Function for a domain maintained by IBM Cloud Internet Services. You can use this sample even if your DNS provider is not Cloud Internet Services.
Once your endpoint is ready, create an instance of IBM Cloud Certificate Manager (or go to your existing instance), and in the
Settings tab, add a Callback URL Notification Channel and point it to your domain validation endpoint URL.
- Your callback URL endpoint must use the HTTPS protocol.
- When a Certificate Manager instance is created, a unique private and public key pair is generated. The private key is used to sign all notification payloads sent from the instance. In your callback URL endpoint, you should use your instance public key to verify that the payload wasn't altered by a third party.
- Check the notification payload's
instance_crnvalue against a whitelist of your Certificate Manager instance(s) CRN(s) that you can keep in your endpoint code. This is to make sure only your Certificate Manager instances are allowed to execute your code. If someone somehow gets your callback URL and tries to misuse it, they won't be able to.
- Use the lowest privilege role that is allowed to access domain DNS records. Avoid hard-coding API keys or credentials used to add/remove TXT records in your DNS provider.
The sample code we provided demonstrates how to take these security considerations into account.
Ordering a certificate
To order a certificate, go to the Certificate Manager's Manage tab, click Order Certificate, and provide the following:
- Certificate name
- Primary domain and any alternative domains
- Algorithm and key algorithm.
Your order status will be
Pending while your order is being processed.
Once the domain validation challenge(s) are fulfilled, your certificate will be issued to you and the certificate status will change to
Valid. You can then deploy your certificate and associated private key to services in IBM Cloud that do SSL/TLS termination for your apps (e.g. IBM Kubernetes Service Ingress, or API Connect), or download your your certificate and key from Certificate Manager to use elsewhere.
You'll get a notification when your certificate is ready (or if there was a problem) in your Slack and/or Callback URL notification channels.
Q: Why is my order status
Pending for a long time?
A: On slow DNS networks, an order may take up to about 20 minutes to complete successfully.
Q: For how long will Certificate Manager try to validate the domain? A: After sending the domain validation challenge, Certificate Manager will try to validate the domain for up to 10 minutes.
Q: How do I programmatically check the certificate order status using the Certificate Manager public API?
A: Use the
Get certificate metadata API to poll the certificate order status.
Q: Why am I not receiving certificate order events in my existing Slack notification channel? A: Upgrade your Slack notification channel to the latest version in the Certificate Manager Settings tab.
Questions and feedback
You can get help with technical questions on Stack Overflow with the ‘ibm-certificate-manager’ tag, or you can find help for non-technical questions in IBM developerWorks with the ‘ibm-certificate-manager’ tag. For defect or support needs, use the support section in the IBM Cloud menu. We would love to hear your feedback.
To get started with Certificate Manager, check it out in the IBM Cloud catalog.