Skip to main content

ACME client setup based on Certbot for dns-01 challenges via Azure Cloud services

Project description

Introduction

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

Installing acme-dns-azure

acme-dns-azure is available on PyPi:

python -m pip install acme-dns-azure

For usage examples please refer to targets

Scope

Based on the provided configuration and trigger, the wrapper library supports following flow.

architecture

  1. Receive certificates, receive EAB & ACME credentials (if configured), receive ACME account information (if already present)
  2. Certbot: Init Renewal process to certificate Authority
  3. Certbot: DNS Challenge - create TXT record
  4. Certbot: Renew certificates
  5. Certbot: DNS Challenge - delete TXT record
  6. Upload renewed certificates, create/update ACME account information as secret

Features

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
  • (Planned) User Assigned Identity

Integration

The library can be used by:

  • running as script
  • (Planned): Python package within your app

Within targets you can find example implementations for running the python package:

  • (Planned): Azure function
  • (Planned): container

usage

Contribute

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 targets support and activate it:

Install dependencies

poetry install --all-extras
source .venv/bin/activate

Lint

poetry run black .

Run unit tests

poetry run coverage run
poetry run coverage report

Run integration tests

See tests/integration

Usage

Config

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 values true or false
  • <int>: a regular integer
  • <string>: a regular string
  • <secret>: a regular string that is a secret, such as a password
  • <regex>: a regular expression

The other placeholders are specified separately.

See example for 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: 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

[<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 library

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

Permission Handling

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.mydomain 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

acme_dns_azure-0.1.1.tar.gz (16.1 kB view hashes)

Uploaded Source

Built Distribution

acme_dns_azure-0.1.1-py3-none-any.whl (16.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page