acme-http-01-azure-key-vault-middleware

Use Let's Encrypt and other RFC 8555 providers natively and securely on Azure.

Supports Azure Web Apps, Azure Functions, Azure Front Door, Azure CDN, and services outside of Azure.

We use popular and high-quality industry standard libraries: node-fetch, node-forge, @azure/keyvault-*.

Breaking changes

In 2.0.0, we further restricted access policy for web server. Please change it from "get secret" to "list secret".

Why another ACME middleware?

Unlike Greenlock, the whole operation is done over Azure Key Vault. It gives us a few benefits:

• Inexpensive
• Use on all Azure services and beyond
• Easy to set up
• Isolated access policies to Key Vault
• Minimal code on middleware
• Secure by default: no database, file system, or other forms of storage

Inexpensive

Estimated cost for Azure Key Vault on each certificate issued by Let's Encrypt is less than USD 0.10 per month, given 1 certificate renewal per week.

Use on all Azure services and beyond

Certificates stored in Azure Key Vault is available to use for all Azure services, such as Azure Web Apps, Azure Functions, Azure Front Door, Azure CDN, etc.

If you prefer to use certificates outside of Azure, you can always export the certificate as PFX.

Easy to set up

The solution is cloud native and easy to set up.

1. Set up Azure Key Vault
2. Install the middleware
3. Run enrollment agent periodically
4. Bind the SSL certificate to your Azure Web Apps or Azure Functions

Isolated access policies to Key Vault

Isolated access policies design means better security.

| Role | Key | Secrets | Certificates | | ---------------- | --------- | -------- | ------------ | | Enrollment agent | Get, Sign | Get, Set | Import | | Web server | | List | |

"List secrets" policy do not have access to the content of secret.

Minimal code on middleware

The middleware is only used to statically serve responses generated by the enrollment agent. It do not have access to the ACME account credentials or certificates.

If you are not on Express, you can consider porting it to platform of your choice. It is about 50 lines only.

Secure by default: no database, file system, or other forms of storage

We are using Azure Key Vault for storing the certificate and ACME challenges. It is designed to store certificates securely and integrates seamlessly with other Azure services.

You can use the certificates on Azure Functions and ZIP file deployment on Azure Web Apps. ZIP file deployment disable access to local file system, which improves security and reduce deployment time.

Unlike other Certbot implementation, we do not ship with any web UI for ordering certificates. This is to prevent unintended exposure of the website. We recommend running the enrollment agent in a secure environment, such as your CI/CD environment.

Set up

In this sample setup, we are assuming you are installing SSL certificates for an Express web server hosted on Azure Web Apps.

1. Set up Azure Key Vault
   1. Create a new Azure Key Vault
   2. Set up ACME account key
   3. Create Service Principal Names
   4. Assign access policies to Service Principal Names
2. Using the middleware
   1. Set up environment variables in Azure Web Apps
   2. Install NPM packages
   3. Enable custom domain
3. Running enrollment agent
4. Setting up SSL bindings

Set up Azure Key Vault

Create a new Azure Key Vault

It is recommended to set up a new Azure Key Vault resource for each certificate.

Visit https://portal.azure.com/#create/Microsoft.KeyVault to create a new Azure Key Vault.

Set up an account key for your ACME provider

On your Azure Key Vault, generate or import a key to use with your ACME provider. For Let's Encrypt, it support key algorithm EC P-256.

You can follow this article to add a key.

Create Service Principal Names

Create Service Principal Names using Azure CLI. az is preinstalled on Azure Cloud Shell and can be accessed using Azure Portal or Windows Terminal.

az ad sp create-for-rbac -n http://mydomain.com/acme-enrollment-agent --skip-assignment
az ad sp create-for-rbac -n http://mydomain.com/acme-web-server --skip-assignment

Write down both results. We will use it throughout this guide.

These steps are from this article.

Assign access policies to Service Principal Names

On your Azure Key Vault, add access policies for each SPNs. Follow this article to assign new access policies.

| SPN | Key | Secrets | Certificates | | ------------------------------------------- | --------- | -------- | ------------ | | http://mydomain.com/acme-enrollment-agent | Get, Sign | Get, Set | Import | | http://mydomain.com/acme-web-server | | List | |

Using the middleware

You can use the SSL certificate on any services supported by Azure Key Vault. For simplicity, we are setting it up on Express hosted on Azure Web Apps.

You can also use this package on Azure Functions, please refer to this article.

Set up environment variables in Azure Web Apps

Add the following environment variables to your Azure Web Apps resource. This is the credential for SPN http://mydomain.com/acme-web-server.

AZURE_CLIENT_ID=12345678-1234-5678-abcd-12345678abcd
AZURE_CLIENT_SECRET=12345678-1234-5678-abcd-12345678abcd
AZURE_TENANT_ID=12345678-1234-5678-abcd-12345678abcd
KEY_VAULT_NAME: my-key-vault

If you prefer to use other forms for authentication, such as certificate-based credential, you can refer to this article for details.

AZURE_CLIENT_ID is the appId from the result of SPN creation. AZURE_CLIENT_SECRET is password, and AZURE_TENANT_ID is tenant.

Install NPM packages

Install both @azure/identity and acme-http-01-azure-key-vault-middleware package.

npm install @azure/identity acme-http-01-azure-key-vault-middleware

In your Express app, attach the middleware. It will mount to all GET requests to /.well-known/acme-challenge/.

const { DefaultAzureCredential } = require('@azure/identity');
const createACMEMiddleware = require('acme-http-01-azure-key-vault-middleware/express');

app.use(
  createACMEMiddleware({
    azureCredential: new DefaultAzureCredential(),
    azureKeyVaultName: process.env.KEY_VAULT_NAME
  })
);

Optionally, you can pass a rateLimiter option for throttling requests. By default, the middleware use in-memory rate limiter and throttle at a rate of 10 requests per second and 100 requests per 5 minutes.

Enable custom domain

Follow this article to add your custom domain to your Azure Web Apps. Or this article for Azure Functions.

Running enrollment agent

To avoid rate-limiting by your SSL provider, you should not order new certificate more than once a week. Let's Encrypt allows 50 certificates per registered domain per week.

You should run the enrollment steps periodically in your scheduler, such as cron or GitHub Actions.

Before running the enrollment agent, set the following environment variables. This is the credential for SPN http://mydomain.com/acme-enrollment-agent.

ACME_ACCOUNT_CONTACTS=mailto:[email protected]
ACME_ACCOUNT_TOS_AGREED=1
ACME_DIRECTORY_URL=https://acme-v02.api.letsencrypt.org/directory

AZURE_CLIENT_ID=12345678-1234-5678-abcd-12345678abcd
AZURE_CLIENT_SECRET=12345678-1234-5678-abcd-12345678abcd
AZURE_TENANT_ID=12345678-1234-5678-abcd-12345678abcd

KEY_VAULT_ACME_ACCOUNT_KEY_NAME=my-acme-key
KEY_VAULT_CERTIFICATE_NAME=my-ssl-certificate
KEY_VAULT_NAME=my-key-vault

DOMAINS=mydomain.com,myanotherdomain.com

For testing purpose, you should order it from https://acme-staging-v02.api.letsencrypt.org/directory instead.

Then, run:

npx -p acme-http-01-azure-key-vault-middleware@1 order

If succeeded, you should see:

Creating or signing into ACME provider.
Creating a new certificate order.
Order created at https://acme-v02.api.letsencrypt.org/acme/order/12345678/23456789.
Preparing HTTP-01 challenge responses.
Waiting for order to become ready.
Order is ready for pickup (finalize) at https://acme-v02.api.letsencrypt.org/acme/finalize/12345678/34567890.
Downloading certificate from https://acme-v02.api.letsencrypt.org/acme/cert/1234567890abcdef1234567890abcdef12345678.
Certificate downloaded, serial number is 1234567890abcdef1234567890abcdef12345678 and will expires at 2021-01-01T12:34:56.789Z.
Uploading certificate to Azure Key Vault as "my-ssl-certificate".
Certificate uploaded to Azure Key Vault as "my-ssl-certificate".

Setting up SSL bindings

After the first SSL certificate is uploaded to Azure Key Vault, you can start using it in your Azure Web Apps. Follow this tutorial to enable SSL on web app.

https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-certificate#import-a-certificate-from-key-vault

If you are using the certificates on Azure Functions, please follow this tutorial.

Going production

Here is a non-exhaustive list of things your team should consider when adopting this package in your production environment.

As always, when deploying code to production environment, your team should always review code produced by third parties.

Throttling requests

HTTP-01 challenge requires public GET request to /.well-known/acme-challenge/. And every GET request to this endpoint will trigger an Azure Key Vault operation.

By default, in our Express middleware, we use rate-limiter-flexible with memory-based bursty throttling, up to 50 requests per second or 100 requests per 5 minutes. If spam attack occurs at extreme rate, it will cost about USD 3 per month per server (based on Azure Key Vault pricing at the time of this writing, at USD 0.03/10,000 operations).

You can configure throttling by passing your own RateLimiter object.

const { BurstyRateLimiter, RateLimiterMemory } = require('rate-limiter-flexible');

app.use(
  createACMEMiddleware({
    azureCredential: new DefaultAzureCredential(),
    azureKeyVaultName: 'my-key-vault',
    rateLimiter: new BurstyRateLimiter(
      new RateLimiterMemory({
        duration: 300,
        points: 100
      }),
      new RateLimiterMemory({
        duration: 1,
        points: 50
      })
    )
  })
);

To disable throttling, pass a falsy value to rateLimiter option.

Allow-listing IP addresses

If your SSL provider publish IP addresses of their HTTP-01 challengers, you should allow-list them to reduce attack surface.

Logging

You may want to log all requests made to /.well-known/acme-challenge/ for monitoring this attack surface.

Contributing

(TBD)

Greenlock™ is a trademark of AJ ONeal