Sławek Koszewski slawek

Joined on 2023-10-09

@slawek/azure-acme-provisioner (0.6.2)

Published 2026-05-23 10:34:34 +02:00 by slawek in slawek/azure-acme-provisioner

Set up this registry in your project .npmrc file:

@slawek:registry=https://gitea.koszewscy.waw.pl/api/packages/slawek/npm/

To install the package using npm, run the following command:

npm install @slawek/azure-acme-provisioner@0.6.2

or add it to the package.json file:

"@slawek/azure-acme-provisioner": "0.6.2"

For more information on the npm registry, see the documentation.

Azure ACME Provisioner

Azure ACME Provisioner is a NodeJS package that provides necessary tools to automate the process of obtaining SSL/TLS certificates from ACME (Automatic Certificate Management Environment) compliant certificate authorities, such as Let's Encrypt, for applications hosted on Microsoft Azure. It uses Azure KeyVault to securely store and manage the obtained certificates and ACME account credentials. The package may function as a standalone tool, a docker image, as a library or as an Azure Function, making it versatile for various deployment scenarios.

Features

Uses ACME protocol to automate certificate issuance and renewal.
Stores ACME account information as secrets in Azure KeyVault for secure management.
Stores obtained SSL/TLS certificates in Azure KeyVault for easy access and management.
Automatically scans configured Azure DNS zones to identify records that require certificates (uses the acme tag to identify relevant recordsets).

Requirements

Node.js 24 or later
Azure subscription with:
- Azure DNS zone(s) with records tagged acme: true or acme: enabled
- Azure Key Vault instance
- Managed Identity (or service principal) with permissions to read/write Key Vault secrets and certificates, and to manage DNS record sets

Installation

npm install azure-acme-provisioner

Or use the CLI directly via npx:

npx azure-acme-provisioner --help

DNS Zone Tagging

The provisioner discovers domains by scanning Azure DNS zones. Tag a zone or individual A/CNAME recordsets with acme: true to include them:

Zone-level tag — issues certificates for both the zone apex (example.com) and a wildcard (*.example.com) as a single SAN order.
Recordset-level tag — issues a certificate for that specific FQDN.

CLI Usage

All commands share a common set of options. Required options vary per command and are listed in each section below.

Common options

Option	Description
`--keyvault-name <name>`	Azure Key Vault name (constructs `https://<name>.vault.azure.net`)
`--keyvault-url <url>`	Azure Key Vault URL — use for sovereign clouds or non-standard URLs
`--subscription-id <id>`	Azure subscription ID
`--resource-group <rg>`	Resource group to scan
`--email <email>`	ACME contact email
`--renewal-threshold <days>`	Days before expiry to trigger renewal (default: 30)
`--log-level <level>`	`debug` \| `info` \| `warn` \| `error` (default: `info`)

Scanning scope

The run, scan, status, and renew commands accept optional positional arguments to narrow the scope:

Arguments	Scope
(none)	All tagged records in all DNS zones in the subscription
`--resource-group <rg>`	All tagged records in all DNS zones in the resource group
`--resource-group <rg> <zone>`	All tagged records in the specified DNS zone
`--resource-group <rg> <zone> <name> [name...]`	Specific record names in the zone — bypasses tag filtering

Record names are the DNS label within the zone (e.g. api, www, @ for apex, * for wildcard). FQDNs are constructed by appending the zone name.

`run [zone] [names...]` — issue or renew certificates

Issues or renews certificates for all domains in scope.

Required: --keyvault-name or --keyvault-url, --subscription-id, --email

# All tagged records in the subscription
azure-acme-provisioner run \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --email admin@example.com

# All tagged records in a resource group
azure-acme-provisioner run \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --resource-group my-dns-rg \
  --email admin@example.com

# All tagged records in a specific zone
azure-acme-provisioner run \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --resource-group my-dns-rg \
  --email admin@example.com \
  example.com

# Specific records (bypasses tags)
azure-acme-provisioner run \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --resource-group my-dns-rg \
  --email admin@example.com \
  example.com api www

Option	Description
`--http <port>`	Use HTTP-01 challenge on the given port instead of DNS-01
`--pem`	Store certificates as PEM bundle instead of PFX (PKCS#12)
`--dry-run`	Show what would be issued or renewed without making changes

`scan [zone] [names...]` — list FQDNs in scope

Lists all FQDNs for which certificates will be issued, along with their zone and resource group.

Required: --subscription-id

azure-acme-provisioner scan \
  --subscription-id <subscription-id> \
  --resource-group my-dns-rg

Option	Description
`--output table\|json`	Output format (default: `table`)

`status [zone] [names...]` — show certificate expiry

Shows the expiry date and days remaining for each domain's certificate.

Required: --keyvault-name or --keyvault-url, --subscription-id

azure-acme-provisioner status \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --resource-group my-dns-rg

Option	Description
`--output table\|json`	Output format (default: `table`)

`renew [zone] [names...]` — force-renew certificates

Force-renews certificates in scope, bypassing the renewal threshold. Accepts the same scope arguments as run.

Required: --keyvault-name or --keyvault-url, --subscription-id, --email

# Renew all managed certificates
azure-acme-provisioner renew \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --email admin@example.com

# Renew specific records in a zone (bypasses tags)
azure-acme-provisioner renew \
  --keyvault-name myvault \
  --subscription-id <subscription-id> \
  --resource-group my-dns-rg \
  --email admin@example.com \
  example.com api www

Option	Description
`--http <port>`	Use HTTP-01 challenge on the given port instead of DNS-01
`--pem`	Store certificates as PEM bundle instead of PFX (PKCS#12)

`download <fqdn>` — download a certificate

Fetches the certificate bundle from Key Vault and writes it to stdout or a file.

Required: --keyvault-name or --keyvault-url

# Print to stdout
azure-acme-provisioner download api.example.com --keyvault-name myvault

# Write to a file
azure-acme-provisioner download api.example.com --keyvault-name myvault --output api.example.com.pfx

Option	Description
`--output <file>`	Write to file instead of stdout

`convert <fqdn>` — convert certificate format

Converts a stored certificate between PFX (PKCS#12) and PEM format in-place.

Required: --keyvault-name or --keyvault-url

# Convert to PFX (default)
azure-acme-provisioner convert api.example.com --keyvault-name myvault

# Convert to PEM bundle
azure-acme-provisioner convert api.example.com --keyvault-name myvault --pem

Option	Description
`--pem`	Convert to PEM bundle instead of PFX (PKCS#12)

`assign-role <fqdn>` — assign Key Vault RBAC roles

Assigns Key Vault Certificate User and Key Vault Secrets User roles to a principal for the certificate and secret objects corresponding to the given FQDN.

Required: --principal-id, --principal-type, --keyvault-resource-group, --keyvault-name or --keyvault-url, --subscription-id

azure-acme-provisioner assign-role api.example.com \
  --principal-id <object-id> \
  --principal-type ServicePrincipal \
  --keyvault-resource-group my-kv-rg \
  --keyvault-name myvault \
  --subscription-id <subscription-id>

Option	Description
`--principal-id <id>`	Object ID of the Azure principal to assign roles to
`--principal-type <type>`	`User` \| `Group` \| `ServicePrincipal` (use `ServicePrincipal` for managed identities)
`--keyvault-resource-group <rg>`	Resource group that contains the Key Vault
`--dry-run`	Show what would be assigned without making changes

Challenge methods

By default run and renew use DNS-01 via Azure DNS (requires DNS Zone Contributor role).

Pass --http <port> to use HTTP-01 instead. The provisioner starts a temporary Express HTTP server on the given port and shuts it down after each certificate is issued. The ACME CA always validates against port 80, so either pass --http 80 directly, or run the listener on a non-privileged port and forward port 80 to it externally (reverse proxy, NAT rule, or Docker port mapping).

# DNS-01 (default)
azure-acme-provisioner run --keyvault-name myvault --subscription-id <id> --email admin@example.com

# HTTP-01 on port 80
azure-acme-provisioner run --keyvault-name myvault --subscription-id <id> --email admin@example.com --http 80

# HTTP-01 on a non-privileged port (useful behind a reverse proxy or NAT rule)
azure-acme-provisioner run --keyvault-name myvault --subscription-id <id> --email admin@example.com --http 8080

Note: Binding port 80 requires root privileges or CAP_NET_BIND_SERVICE. When running in Docker, map the host port to the container: -p 80:8080 and pass --http 8080.

Configuration

All configuration is via environment variables. CLI flags override env vars when both are provided.

Required

Variable	Description
`ACME_KEYVAULT_URL`	Azure Key Vault URL, e.g. `https://myvault.vault.azure.net`
`ACME_SUBSCRIPTION_ID`	Azure subscription ID
`ACME_CONTACT_EMAIL`	Contact email registered with the ACME CA

Optional

Variable	Default	Description
`ACME_RESOURCE_GROUP`	all resource groups in subscription	Resource group to scan
`ACME_DNS_ZONE`	all zones in resource group	DNS zone name to restrict scanning
`ACME_CERT_NAMES`	tag-based discovery	Comma-separated record names within the zone — bypasses tag filtering
`ACME_DIRECTORY_URL`	Let's Encrypt production	ACME directory URL
`ACME_RENEWAL_THRESHOLD_DAYS`	`30`	Renew certificates this many days before expiry
`ACME_DNS_PROPAGATION_WAIT`	`60`	Maximum seconds to wait for DNS TXT record propagation
`ACME_DNS_CHALLENGE_TTL`	`60`	TTL (seconds) for DNS-01 challenge TXT records
`ACME_HTTP_PORT`	unset	If set to a positive integer, use HTTP-01 challenge on that port instead of DNS-01
`ACME_CERT_FORMAT`	`pfx`	Certificate storage format: `pfx` (PKCS#12) or `pem`
`ACME_LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, `error`
`ACME_SCHEDULE`	`0 0 2 * * *`	Azure Function timer schedule (cron expression, 6-field format). Only used when deployed as an Azure Function.

Azure Authentication

The provisioner uses DefaultAzureCredential from @azure/identity, which tries authentication methods in this order:

Managed Identity — recommended for Azure-hosted deployments (Functions, ACI, AKS). Assign a system or user-assigned managed identity with the required RBAC roles. No credential configuration needed.
Workload Identity Federation — for Kubernetes or CI/CD (GitHub Actions). Set AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE. No secrets required.
Certificate-based service principal — set AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_CERTIFICATE_PATH (optionally AZURE_CLIENT_CERTIFICATE_PASSWORD, AZURE_CLIENT_SEND_CERTIFICATE_CHAIN).
Client secret service principal — set AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET. Least secure; use only as a last resort.
Azure CLI / Developer CLI — used automatically in local development when logged in via az login or azd auth login.

For sovereign clouds (Azure Government, Azure China), set AZURE_AUTHORITY_HOST to the appropriate authority endpoint.

Azure Function

The package includes an Azure Functions v4 timer trigger that runs the provisioner daily at 02:00 UTC.

The function app requires a Managed Identity with the following RBAC assignments:

Scope	Role
Key Vault instance	Key Vault Certificates Officer
Key Vault instance	Key Vault Secrets Officer
Each DNS zone	DNS Zone Contributor

Note: The only DNS changes made are temporary _acme-challenge.<domain> TXT records created during the DNS-01 challenge and deleted immediately after validation. No A, CNAME, or other records are modified. If you require tighter permissions than DNS Zone Contributor, create a custom role limited to Microsoft.Network/dnszones/TXT/write and Microsoft.Network/dnszones/TXT/delete.

Deploying with Azure Functions Core Tools

Prerequisites: Azure CLI, Azure Functions Core Tools v4, Node.js 24.

1. Log in to Azure

az login

2. Create a resource group and storage account (skip if they already exist)

az group create --name <resource-group> --location <location>

az storage account create \
  --name <storage-account-name> \
  --resource-group <resource-group> \
  --location <location> \
  --sku Standard_LRS

3. Create the Function App

az functionapp create \
  --name <function-app-name> \
  --resource-group <resource-group> \
  --storage-account <storage-account-name> \
  --consumption-plan-location <location> \
  --runtime node \
  --runtime-version 24 \
  --functions-version 4

4. Assign a system-assigned Managed Identity

az functionapp identity assign \
  --name <function-app-name> \
  --resource-group <resource-group>

Note the principalId from the output — you will need it in the next step.

5. Grant RBAC roles to the Managed Identity

# Key Vault Certificates Officer
az role assignment create \
  --assignee <principalId> \
  --role "Key Vault Certificates Officer" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<kv-resource-group>/providers/Microsoft.KeyVault/vaults/<keyvault-name>

# Key Vault Secrets Officer
az role assignment create \
  --assignee <principalId> \
  --role "Key Vault Secrets Officer" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<kv-resource-group>/providers/Microsoft.KeyVault/vaults/<keyvault-name>

# Option A — per zone (minimum permission, repeat for each managed DNS zone)
az role assignment create \
  --assignee <principalId> \
  --role "DNS Zone Contributor" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<dns-resource-group>/providers/Microsoft.Network/dnszones/<zone-name>

# Option B — per resource group (convenient when all DNS zones are in one group)
az role assignment create \
  --assignee <principalId> \
  --role "DNS Zone Contributor" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<dns-resource-group>

6. Configure production application settings

az functionapp config appsettings set \
  --name <function-app-name> \
  --resource-group <resource-group> \
  --settings \
    "ACME_KEYVAULT_URL=https://<keyvault-name>.vault.azure.net" \
    "ACME_SUBSCRIPTION_ID=<subscription-id>" \
    "ACME_RESOURCE_GROUP=<dns-resource-group>" \
    "ACME_CONTACT_EMAIL=<email>" \
    "ACME_SCHEDULE=0 0 2 * * *"

7. Build and deploy

npm run build
func azure functionapp publish <function-app-name> --no-build

--no-build tells func to skip its own build step since we already compiled the TypeScript output. To also push application settings from local.settings.json in the same step, append --publish-local-settings --overwrite-settings. This is useful for the initial deployment or when settings and code change together.

Local testing

Create local.settings.json at the project root (gitignored) and fill in your values:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "ACME_KEYVAULT_URL": "https://<keyvault-name>.vault.azure.net",
    "ACME_SUBSCRIPTION_ID": "<subscription-id>",
    "ACME_RESOURCE_GROUP": "<dns-resource-group>",
    "ACME_CONTACT_EMAIL": "<email>",
    "ACME_SCHEDULE": "0 0 2 * * *"
  }
}

Then run:

npm run build
func start

Docker

docker run --rm \
  -e ACME_KEYVAULT_URL=https://myvault.vault.azure.net \
  -e ACME_SUBSCRIPTION_ID=<subscription-id> \
  -e ACME_RESOURCE_GROUPS=my-rg \
  -e ACME_CONTACT_EMAIL=admin@example.com \
  ghcr.io/your-org/azure-acme-provisioner

When running in Azure Container Instances with a user-assigned Managed Identity, set AZURE_CLIENT_ID to the identity's client ID. No other credential variables are needed.

Library Usage

import { Provisioner, loadConfig } from 'azure-acme-provisioner';

const config = loadConfig(); // reads from environment variables
const provisioner = new Provisioner(config);
const result = await provisioner.run();
console.log(result);

Certificate Storage

Certificates are stored as native Azure Key Vault Certificates in PFX (PKCS#12) format (application/x-pkcs12) by default, making them directly consumable by Azure App Service, API Management, and other Azure services that integrate with Key Vault. Pass --pem (or set ACME_CERT_FORMAT=pem) to store as a PEM bundle (application/x-pem-file) instead. Use the convert command to change the format of an already-stored certificate.

ACME account credentials (private key and account URL) are stored as Key Vault Secrets and reused across runs.

Certificate names are derived from the domain: dots are replaced with hyphens, wildcards become wildcard-, and a cert- prefix is added. For example:

Domain	Key Vault certificate name
`api.example.com`	`cert-api-example-com`
`*.example.com`	`cert-wildcard-example-com`

AI Disclaimer

The files in this repository may contain code generated by AI tools. While we strive to ensure the quality and security of all code, we recommend reviewing any AI-generated code before using it in production environments.

Dependencies

ID	Version
@azure/arm-authorization	^9.0.0
@azure/arm-dns	^5.1.0
@azure/functions	^4.14.0
@azure/identity	^4.13.1
@azure/keyvault-certificates	^4.10.3
@azure/keyvault-secrets	^4.11.2
@peculiar/x509	^2.0.0
acme-client	^5.4.0
commander	^14.0.0
express	^5.2.1
node-forge	^1.4.0

Development Dependencies

ID	Version
@types/express	^5.0.6
@types/node	^24.0.0
@types/node-forge	^1.3.14
rimraf	^6.1.3
typescript	^6.0.0

Details

npm

slawek/azure-acme-provisioner

2026-05-23 10:34:34 +02:00

Sławomir Koszewski

MIT

latest

19 KiB

Assets (1)

azure-acme-provisioner-0.6.2.tgz 19 KiB

Versions (1) View all

0.6.2

2026-05-23

Issues

@slawek/azure-acme-provisioner (0.6.2)

Installation

About this package

Azure ACME Provisioner

Features

Requirements

Installation

DNS Zone Tagging

CLI Usage

Common options

Scanning scope

run [zone] [names...] — issue or renew certificates

scan [zone] [names...] — list FQDNs in scope

status [zone] [names...] — show certificate expiry

renew [zone] [names...] — force-renew certificates

download <fqdn> — download a certificate

convert <fqdn> — convert certificate format

assign-role <fqdn> — assign Key Vault RBAC roles

Challenge methods

Configuration

Required

Optional

Azure Authentication

Azure Function

Deploying with Azure Functions Core Tools

Local testing

Docker

Library Usage

Certificate Storage

AI Disclaimer

Dependencies

`run [zone] [names...]` — issue or renew certificates

`scan [zone] [names...]` — list FQDNs in scope

`status [zone] [names...]` — show certificate expiry

`renew [zone] [names...]` — force-renew certificates

`download <fqdn>` — download a certificate

`convert <fqdn>` — convert certificate format

`assign-role <fqdn>` — assign Key Vault RBAC roles