This repository aims to leverage the automatic renewal of SSL certficates within Azure Cloud in a secure manner.
A wrapper library is provided to automatically renew certifactes based on the ACME DNS-01 challenge by using certbot.
The library supports the usage of best practices for securely handling certificates by:
- using certbot
- removing the need of a file system for storing certificates
- Azure Key Vault for central and only storage of secrets and certificates
- enabling easy and flexible automation
acme-dns-azure is available on PyPi:
python -m pip install acme-dns-azure
For usage exampless please refer to examples
Based on the provided configuration and trigger, the wrapper library supports following flow.
- Receive certificates, receive EAB & ACME credentials (if configured), receive ACME account information (if already present) from KeyVault. Resolve DNS and setup certbot related configuration.
- Certbot: Init renewal process to certificate authority
- Certbot: DNS Challenge - create TXT record
- Certbot: Renew certificates
- Certbot: DNS Challenge - delete TXT record
- Upload renewed certificates, create/update ACME account information as secret within KeyVault.
Note: When using DNS delegation step 3. and 5. differ as the TXT record won´t be deleted.
The library handles following use cases:
- Create new certificates
- Update domain references in existing certificates
- Renew existing certificates
Auth is possible by using:
- Service Principal
- User Assigned Identity
The library can be used by:
- running as script
- Python package within your app
Within examples you can find example implementations for running the python package:
- Azure function
- Container
Fork, then clone the repo:
git clone https://github.com/ZEISS/acme-dns-azure
Install Poetry if you not have it already:
curl -sSL https://install.python-poetry.org | python3 -
Configure the virtual environment with full example support and activate it:
poetry install --all-extras
source .venv/bin/activate
poetry run black .
poetry run coverage run
poetry run coverage report
See How to run integration tests
For releasing a new version, create a PR with one of following labels:
- minor
- major
- patch
- prepatch
- preminor
- premajor
- prerelease
The config is written in YAML format, defined by the scheme described below. Brackets indicate that a parameter is optional. For non-list parameters the value is set to the specified default.
Generic placeholders are defined as follows:
<boolean>
: a boolean that can take the valuestrue
orfalse
<int>
: a regular integer<string>
: a regular string<secret>
: a regular string that is a secret, such as a password
The other placeholders are specified separately.
See examples for configuration examples.
# Azure credentials choice section. Only one of the following flags should be set to true to indicate which credentials to use. Otherwise an exception would be raised by the validator.
# These values are translated into ini file as specified here: https://docs.certbot-dns-azure.co.uk/en/latest/index.html#certbot-azure-workload-identity-ini
# If no flag is provided the program will try to use sp_client_* values to use service principal credentials first. If those are not both present it will try to use managed_identity_id.
[use_system_assigned_identity_credentials: <boolean>]
[use_azure_cli_credentials: <boolean>]
[use_workload_identity_credentials: <boolean>]
[use_managed_identity_credentials: <boolean>]
[use_provided_service_principal_credentials: <boolean>]
# Client ID of managed identity. Must be provided if use_managed_identity_credentials is true. Will be used even if all use_*_credentials flags are set to false, but only if sp_client_* values are not all provided.
[managed_identity_id: <string>]
# sp_client_* values must be provided if use_provided_service_principal_credentials is true. Will be used even if all use_*_credentials flags are set to false. User must specify id and either secret or certificate path. If both values (id and pwd/cert path) are provided and none of the flags is set to true it has precedence over the use of provided managed_identity_id.
[sp_client_id: <string>]
[sp_client_secret: <secret>]
[sp_certificate_path: <string>]
# End of Azure credentials choice section.
[azure_environment: <string> | default = "AzurePublicCloud"]
# Flag if existing certificates containing multiple domains should be renewed and updated based on the definition of the config file. If not set, mismatching certificates will be skipped.
[update_cert_domains: <boolean> | default = False]
# key vault uri for renewal of certifcate
key_vault_id : <string>
# ACME Certificate Authority
server : <string>
# Secret name within key vault for storing ACME Certificate authority account information
[keyvault_account_secret_name: <regex> | default "acme-account-$(network location of server)"]
# when server=https://example.com/something, then keyvault_account_secret_name="acme-account-example-com"
# config file content for certbot client
[certbot.ini : <string> | default = ""]
NOTE: Either managed_identity_id or sp_client_id and sp_client_secret must be specified.
NOTE: certbot.ini represents the CERTBOT configuration file and will be passed into certbot by the acme_dns_azure library as defined. Misconfiguration will lead to failures of certbot and therefore of the renewal process.
Following values will be added to the configurataion file by the acme_dns_azure library per default:
preferred-challenges: dns
authenticator: dns-azure
agree-tos: true
# External account binding configuration for ACME, with key ID and base64encoded HMAC key
[enabled: <boolean> | default = false]
[kid_secret_name : <string> | default="acme-eab-kid"]
[hmac_key_secret_name : <secret> default="acme-eab-hmac-key"]
certificates:
- <certificate>
# Certbot certficate name. The name will also be used for Azure keyvault certificate name.
name: <string>
# Azure dns zone resource ID used for ACME DNS01 challenge
dns_zone_resource_id: <string>
# renewal in days before expiry for certificate to be renewed. Default is 30
[renew_before_expiry: <int>]
domains:
- <domain>
# domain name this certificate is valid for. Wildcard supported.
name: <string>
# Azure dns zone resource ID used for ACME DNS01 challenge
[dns_zone_resource_id: <string>]
For running the module as script 'sp_client_id' and 'sp_client_secret' are required. 'managed_identity_id' is not supported.
# from config file
python acme_dns_azure/client.py --config-file-path $CONFIG_File_PATH
# from env
python acme_dns_azure/client.py --config-env-var $ENV_VAR_NAME_CONTAINING_CONFIG
Best follow security recommendations from Azure.
When working with shared DNS Zones, one can work with DNS delegation with limited permissions:
Example:
Record | Name | Value | Permission |
---|---|---|---|
TXT | _acme-dedicated | - | DNS Zone Contributor |
CNAME | _acme-challenge.mysubdomain | _acme-dedicated.fqdn. | None |
The CNAME and TXT record must be created upfront to enable users to use certbot. The permissions are required on the identity triggering certbot.
With this setup, a DNS Zone owner can limit permissions and enable Users to Create/Renew certificates for their subdomain and ensuring that users cannot aquire certificates for other domains or interfer with existsing records.