5

How do you trigger Azure CDN to read the latest version of custom certificate from Key Store without downtime?

My CDN-setup is working ok, but given Let's Encrypt, the certificate is short lived and requires automation for updates. Doing az keyvault certificate import is trivial enough on Azure CLI to update the certificate into Key Vault, but what next? How do you tell Azure CDN to start using the new version of the cert?

Failed attempts

  • Waiting for couple hours. Nothing happened.
  • Running az cdn custom-domain enable-https on a domain having the HTTPS already enabled. Result: an internal misconfiguration and couple hours of downtime to first disable the custom domain and then enable it. Certificate was updated, though.

From Azure Portal

Azure Portal tooltip on custom domain certificate version says "Select the version of the certificate you want to use. By default we'll use the latest version." That is true when creating the endpoint, but how do you start using the latest version? The latest version is already selected from dropdown, but I did select the previous version and select the latest version. Doing that enabled "Save".

Saving the form resulted in no-downtime update of the certificate. Nice, but given automation and scripting, not really the way to go.

Things which might do the trick, but I haven't tested yet

  • Applying ARM-template of the CDN-setup
  • Powershell Az.Cdn has Start-AzCdnEndpoint/Stop-AzCdnEndpoint cmdlets. Maybe helpful, but 100% guarantee to generate downtime.

Is there anything I can try on next update cycle?

2

3 Answers 3

7

As of 2021-04-05, Azure CDN can be told to use the "Latest" version of a particular KeyVault certificate. I haven't found any news of this change, but it was added to the documentation with this commit.

In order for the certificate to be automatically rotated to the latest version when a newer version of the certificate is available in your Key Vault, please set the certificate/secret version to 'Latest'. If a specific version is selected, you have to re-select the new version manually for certificate rotation. It takes up to 24 hours for the new version of the certificate/secret to be deployed.

In the portal, this can be done by choosing the "Latest" option in the "Certificate/Secret version" dropdown. With the Azure CLI, this can be done with:

az cdn custom-domain enable-https \
    --resource-group "$cdnResourceGroupName" \
    --profile-name "$cdnProfileName" \
    --endpoint-name "$cdnEndpointName" \
    --name "$cdnCustomDomainName" \
    --user-cert-subscription-id "$subscriptionId" \
    --user-cert-group-name "$keyVaultResourceGroupName" \
    --user-cert-vault-name "$keyVaultName" \
    --user-cert-secret-name "$secretName" \
    --user-cert-protocol-type 'sni'

Notice that this command does not set the --user-cert-secret-version parameter, which is how you select the "Latest" functionality.

For anyone who wants to do it manually, the old answer of doing this manually is below.


Running az cdn custom-domain enable-https on a domain having the HTTPS already enabled. Result: an internal misconfiguration and couple hours of downtime to first disable the custom domain and then enable it.

As of 2021-04-05, this can be done with the Azure CLI with:

az cdn custom-domain enable-https \
    --resource-group "$cdnResourceGroupName" \
    --profile-name "$cdnProfileName" \
    --endpoint-name "$cdnEndpointName" \
    --name "$cdnCustomDomainName" \
    --user-cert-subscription-id "$subscriptionId" \
    --user-cert-group-name "$keyVaultResourceGroupName" \
    --user-cert-vault-name "$keyVaultName" \
    --user-cert-secret-name "$secretName" \
    --user-cert-secret-version "$secretVersion" \
    --user-cert-protocol-type 'sni'

(When this answer was originally written in 2019 May, the Azure CLI documented a --custom-domain-https-parameters parameter that implied it could be used for this purpose. If the parameter was not supplied, the CLI would run the CDN-managed cert workflow (cert issued by DigiCert). However, it was never properly documented how to actually use the parameter. As of 2021 March, the parameter was removed from the CLI again. Finally, as of 2021 April, the --user-cert-* parameters have been added.)

The equivalent feature was added in 2019 March to the .Net SDK,. So the Nuget package should allow you to use user-managed certs.

As of 2021 April, Azure PowerShell's Enable-AzCdnCustomDomainHttps commandlet still does not support user-managed certs, only CDN-managed certs.

Or you can use the REST API directly as documented here. Make a POST request to https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.Cdn/profiles/$cdnProfileName/endpoints/$cdnEndpointName/customDomains/$cdnCustomDomainName/enableCustomHttps?api-version=2018-04-02 with an application/json body that looks like

{
    "certificateSource": "AzureKeyVault",
    "certificateSourceParameters": {
        "@odata.type": "#Microsoft.Azure.Cdn.Models.KeyVaultCertificateSourceParameters",
        "deleteRule": "NoAction",
        "resourceGroupName": "$resourceGroupName",
        "secretName": "$secretName",
        "secretVersion": "$secretVersion",
        "subscriptionId": "$subscriptionId",
        "updateRule": "NoAction",
        "vaultName": "$keyVaultName"
    },
    "protocolType": "ServerNameIndication"
}

$resourceGroupName and $keyVaultName identify the KeyVault. $secretName and $secretVersion identify the certificate. (Don't be confused if the Portal doesn't show any secrets in your KeyVault; a KeyVault certificate with a private key is implicitly a KeyVault secret with the same name and version.)

This API endpoint follows standard REST semantics, in that it returns HTTP 202 Accepted since it's a long-running async operation. It'll set the Location header in the response, and you should GET that URL repeatedly till it resolves to a success or failure status code.

Note that the portal also uses the REST API, so you can always derive this from just doing the steps in the portal UI and inspecting the network requests in your browser's developer tools. You will need to get your own oauth2 token, though (by creating an SP).


Aside: To save people the time it took me to discover this when trying to do this for my own domain, do not be fooled by the documentation or the example in the Azure Rest API specs repo. They imply the API version 2017-10-12 supports customHttpsParameters, but in fact only 2018-04-02 and newer support it. If you use 2017-10-12 then the parameter is silently ignored, and it will try to use the Digicert automatic cert workflow.

6
  • I've used the api version 2017-10-12 and it works fine! This is the same version used by the portal Oct 9, 2019 at 9:25
  • @DiegoMendes 2017-10-12 will not work unless you want to use the DigiCert-provided certs, as I wrote in the answer. And no, the portal does not use 2017-10-12. As of right now it uses 2019-04-15
    – Arnavion
    Oct 9, 2019 at 16:00
  • I am currently using using 2017-10-12 and I can guarantee it works! When I inspected the portal, it was also using the same version Oct 9, 2019 at 18:40
  • @DiegoMendes Again, the question is about using your own cert, not Digicert's automatic cert workflow. The custom cert does not work with 2017-10-12. And again, the portal uses 2019-04-15. Here's proof: i.imgur.com/XpB3kP2.png
    – Arnavion
    Oct 10, 2019 at 4:14
  • I am using with my own cert, believe it or not it works! The domain your showed is to get custom domain,not to setup https certs, the right endpoint is: POST $subscriptionId/resourcegroups/$resourceGroupName/providers/Microsoft.Cdn/profiles/$cdnProfileName/endpoints/$cdnEndpointName/customdomains/$cdnCustomDomainName/enableCustomHttps?api-version=2017-10-12" Oct 10, 2019 at 9:43
0

As suggested by @Arnavion, Azure CDN Custom Domain REST API call can be used to trigger the update of the certificate used by an existing custom domain in Azure CDN. The suggested API docs are at https://learn.microsoft.com/en-us/rest/api/cdn/customdomains/enablecustomhttps. When combining above example with API reference information, it is possible to craft a suitable request with PowerShell 6 Invoke-RestMethod. On success, CDN will start updating the certificate from Key Vault to endpoints in a few minutes.

There is no trickery involved in the operation. All that is needed is to gather all required five parameters for API-required UserManagedHttpsParameters to indicate the exact custom domain in the CDN and pinpoint the X.509 certificate at Key Vault. What is also needed is to combine the parameters with a valid bearer token and then make the mentioned API-call to inform CDN to pick up the new certificate from Key Vault and deploy it to all CDN endpoints.

My script doing all this is available at https://gist.github.com/HQJaTu/c5695626ba51c6194845fa60913e911b

How you get the new certificate into Key Vault is an another discussion and my script won't address that. However, uploading a new version of a certificate is much easier than triggering the CDN-update.

0

At the moment documentation for Azure CLI still doesn't give answer how to do it. I have written some python script to do it as a part the of acme.sh renew-hook. Mainly it works for apex custom domain but you can use it with subdomains. You can find it on github -> https://github.com/przemika/azure-byoc-for-custom-domain

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.