Package: acme-dns-azure
IntroductionThis 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 theACME DNS-01 challengeby usingcertbot.The library supports the usage of best practices for securely handling certificates by:using certbotremoving the need of a file system for storing certificatesAzure Key Vault for central and only storage of secrets and certificatesenabling easy and flexible automationInstalling acme-dns-azureacme-dns-azure is available on PyPi:python-mpipinstallacme-dns-azureFor usage examples please refer totargetsScopeBased 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)Certbot: Init Renewal process to certificate AuthorityCertbot: DNS Challenge - create TXT recordCertbot: Renew certificatesCertbot: DNS Challenge - delete TXT recordUpload renewed certificates, create/update ACME account information as secretFeaturesThe library handles following use cases:Create new certificatesUpdate domain references in existing certificatesRenew existing certificatesAuth is possible by using:Service Principal(Planned) User Assigned IdentityIntegrationThe library can be used by:running as script(Planned): Python package within your appWithintargetsyou can find example implementations for running the python package:(Planned): Azure function(Planned): containerContributeFork, then clone the repo:gitclonehttps://github.com/ZEISS/acme-dns-azureInstall Poetry if you not have it already:curl-sSLhttps://install.python-poetry.org|python3-Configure the virtual environment with full targets support and activate it:Install dependenciespoetryinstall--all-extrassource.venv/bin/activateLintpoetryrunblack.Run unit testspoetryruncoveragerun
poetryruncoveragereportRun integration testsSeetests/integrationUsageConfigThe config is written inYAML 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 valuestrueorfalse<int>: a regular integer<string>: a regular string<secret>: a regular string that is a secret, such as a password<regex>: a regular expressionThe other placeholders are specified separately.Seeexamplefor configuration examples.[managed_identity_id: <string>]

[sp_client_id: <string>]
[sp_client_secret: <secret>]

[azure_environment: <regex> | 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 : <regex>

# ACME Certificate Authority
server : <regex>

# 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: Eithermanaged_identity_idorsp_client_idandsp_client_secretmust be specified.NOTE:certbot.inirepresents theCERTBOT configuration fileand will be passed into certbot by theacme_dns_azurelibrary 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 theacme_dns_azurelibrary per default:preferred-challenges: dns
authenticator: dns-azure
agree-tos: true[<eab>]# External account binding configuration for ACME, with key ID and base64encoded HMAC key
  [enabled: <boolean> |  default = false]
  [kid_secret_name : <regex> | default="acme-eab-kid"]
  [hmac_key_secret_name : <secret> default="acme-eab-hmac-key"]certificates:
  - <certificate><certificate># Certbot certficate name. The name will also be used for Azure keyvault certificate name.
name: <regex>
# renewal in days before expiry for certificate to be renewed
[renew_before_expiry: <int>]
domains:
  - <domain><domain># domain name this certificate is valid for. Wildcard supported.
name: <regex>
# Azure resource ID to according record set within DNS Zone
dns_zone_resource_id: <string>Manual running the libraryFor running the module as script 'sp_client_id' and 'sp_client_secret' are required. 'managed_identity_id' is not supported.# from config filepythonacme_dns_azure/client.py--config-file-path$CONFIG_File_PATH# from envpythonacme_dns_azure/client.py--config-env-var$ENV_VAR_NAME_CONTAINING_CONFIGPermission HandlingBest followsecurity recommendations from Azure.When working with shared DNS Zones, one can work with DNS delegation with limited permissions:Example:RecordNameValuePermissionTXT_acme-dedicated-DNS Zone ContributorCNAME_acme-challenge.mysubdomain_acme-dedicated.mydomainNoneThe 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.