Certbot DNS Azure Authenticator

2.6.1 verified Fri May 01 auth: no python

Azure DNS Authenticator plugin for Certbot. Allows automated Let's Encrypt certificate issuance and renewal via Azure DNS. Current version 2.6.1, requires Python >=3.6. Maintained irregularly with occasional breaking changes.

pip install certbot-dns-azure

Common errors

error certbot: error: --authenticator dns-azure: Plugin 'dns-azure' is not supported ↓

cause Plugin not installed or not recognized by Certbot.

fix

Ensure certbot-dns-azure is installed in the same Python environment as certbot. Run: pip install certbot-dns-azure

error azure.core.exceptions.ClientAuthenticationError: DefaultAzureCredential failed to retrieve a token from the included credentials ↓

cause Managed Identity not properly configured or not running on an Azure resource.

fix

Switch to service principal authentication by setting AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID environment variables or use a credentials file with proper values.

error azure.core.exceptions.ResourceNotFoundError: (ResourceNotFound) Resource group '...' could not be found. ↓

cause Specified Azure resource group for the DNS zone does not exist or the authenticated principal has no access.

fix

Verify the resource group name in the credentials file or environment, and ensure the principal has reader access to the resource group.

error ValueError: Invalid credentials file format. Expected .ini file with sections. ↓

cause Credentials file is not in the required INI format (commonly leftover YAML from older versions).

fix

Convert credentials file to INI format. See https://github.com/terricain/certbot-dns-azure#credentials-file-format

Warnings

breaking v2.0.0+ changed credential file format from YAML to INI. Old YAML files will cause parse errors. ↓

fix Update your credentials file to the new INI format (see README). Example: dns_azure_environment = 'AzureCloud' (optional) and use AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID env vars.

gotcha The plugin requires Azure DNS zones to be in the same subscription as the authenticated principal. If using cross-subscription, you must grant access manually. ↓

fix Ensure the service principal or managed identity has 'DNS Zone Contributor' role on the target zone's subscription.

gotcha Managed Identity authentication (DefaultAzureCredential) is only available in v2.4.0+ and requires the plugin to run on an Azure resource (VM, App Service, etc.) with a system-assigned or user-assigned identity. ↓

fix Upgrade to v2.4.0+ or use service principal authentication.

deprecated Usage of AZURE_AUTH_LOCATION environment variable is deprecated in favor of the credentials file. ↓

fix Use --dns-azure-credentials path instead of env var.

Imports

CertbotDnsAzure
```
from certbot_dns_azure._internal.dns_azure import CertbotDnsAzure
```
Internal import path; plugin is auto-detected by Certbot
AzureClient
```
from certbot_dns_azure._internal.client import AzureClient
```
Use for custom scripting, but normally you don't import directly

Quickstart

Run Certbot with Azure DNS authenticator. The credentials file should contain environment variable references or inline secrets. See warning about managed identity vs service principal.

certbot certonly --authenticator dns-azure --dns-azure-credentials /path/to/azure.ini -d example.com