How to Use Certificate Manager to Avoid Outages Using Callback URLs
Midnight Pager Duty incidents are no fun. Especially when your team forgot to do something as simple as updating an expiring SSL Certificate, causing downtime in your app. Isn’t there some way to make sure this never happens again?
Yep, there is. IBM Cloud Certificate Manager can notify you in advance when your certificates are about to expire.
Certificate Manager is a service that helps you centrally manage SSL/TLS certificates for your apps and services. Certificate Manager keeps track of when your certificates expire, serves as a secure repository for SSL/TLS certificates and keys, and helps you securely deploy certificates to your Cloud apps.
Certificate Manager can post notifications to your Slack channel, or you can provide a callback URL to post notifications to channels like email and Pager Duty and trigger automated processes to renew and then redeploy certificates.
In this blog, we will show you how to use the callback URL feature. In our example, we used a callback URL to automatically open GitHub tasks to remind us to renew certificates. Since GitHub is configured to send us emails, we also get reminded to renew certificates through email. We implemented the callback URL as a Cloud Function using IBM Cloud Functions—an event-driven compute service.
Implementing the flow
We’ll start with creating a Cloud Function. A Cloud Function is a piece of code that runs only in response to a trigger so that you don’t have to pay for or maintain servers while they are idle. To create a Cloud Function, go to the Functions dashboard in IBM Cloud, select the Actions tab, click the Create button, and then click Create a new action. Give the action a name, chose the default package, select a Node.js runtime (the sample code in this blog is compatible with Node.js 8), and click the Create button. Now you are ready to add the code to your Cloud Function.
Download the full code here and copy into the cloud function code section (the example code has been updated to use the latest notification format)
The above code contains four functions:
Certificate Manager notifications are sent as a signed JSON web token (JWT). This allows us to verify that the notification payload was actually sent by our Certificate Manager instance and wasn’t tampered with. In order to verify the signature, we must first get the notifications public key from Certificate Manager. We used the Certificate Manager API to request the notifications public key for our instance. We specified the key format as pem since that is what the jsonwebtoken package supports. You need to update url property in this function with your values.
This function returns a human readable date string from the timestamp.
This function builds issue description according to notification event type. It iterates over the expiring certificates and adds them one-by-one to the description.
IBM Cloud Functions requires a function called main to exist as an entry point for the action. The params object contains the body of the incoming request. Certificate Manager notification body contains a single JSON object with a single property called data that holds the signed JWT string as its value.
When we obtained the public key, we can use it to verify the JWT signature. We’ll use the jsonwebtoken library’s verify function. This function receives the JWT string and a public key and returns the payload decoded if the signature is valid. If not, it will throw an error.
Then we can build issue description with function createIssueBody. If this function returns no value it means that no need to create an issue.
Now we move on to creating the GitHub issue. We will create an issue for each notification (containing a set of certificates that expire in the same timeframe). Before we begin doing that, we’ll need to create a repo to send the issues to (or use an existing one) and create a personal GitHub access token. To create the access token, go to https://github.ibm.com/settings/tokens and generate a new personal access token. Once we have our repo and our personal access token, we can send requests to GitHub’s API to create issues. . For more information about creating GitHub issues, see this link.
You need to update options properties with your values.
Adding a notification channel
Our Cloud function is almost ready; all that’s left to do is to make it available over the net. Select Endpointsfrom the left nav of the Cloud Functions UI, check the Enable as Web Function checkbox, and click the Savebutton. Copy the URL that was added at the bottom of the Web Action section.
The last thing left to do is to connect this Web Action to the Certificate Manager notifications mechanism. Open your Certificate Manager dashboard and select Settings from the left nav. Click the Add Notification Channel button, choose callback url from the channel type drop-down, enter the URL we copied from Cloud Functions, and click the Save button.
Once the channel is saved, you will see it in the notification channel list. You can test your setup by clicking the test connection button. This will send a test notification containing fake data to your Cloud Function and should open a GitHub issue if everything is set up correctly.
From now on, whenever your certificates near expiration, Github issues will be created.
Certificate Manager is available in US-South and is in Beta.
You can get help with technical questions at Stack Overflow with the ‘ibm-certificate-manager’ tag, or you can find help for non-technical questions at 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!