Интеграция с ACME / Let's Encrypt

Обзор

Протокол ACME (используется Let's Encrypt и другими удостоверяющими центрами) поддерживает проверку DNS-01 для подтверждения владения доменом. DNS-01 – единственный тип проверки, который поддерживает wildcard-сертификаты (*.example.com) и не требует HTTP-сервера на целевой машине.

NexDNS предоставляет встроенные интеграции с популярными ACME-клиентами, а также универсальный CLI-хук для любого клиента с поддержкой ручных DNS-хуков.

Все ACME-интеграции требуют API-токен, доступный на тарифе Про и выше. Каждый клиент перед созданием проверочной записи находит зону, поэтому токену нужны права zones.read, а также records.read и records.write. Создайте токен на странице nexdns.ru/settings/api-keys.

Этот экземпляр обслуживает API по адресу https://api.nexdns.ru/v1. Он нужен каждому клиенту ниже: как переменная окружения для acme.sh, как ключ dns_nexdns_api_url для certbot и как --api-url для CLI-хука. Выпущенный провайдер lego такой настройки не принимает – подробнее в его разделе ниже.

Как проверяется wildcard

Проверка – это TXT-запись _acme-challenge в проверяемом имени. Сертификат, который покрывает и example.com, и *.example.com, даёт два разных проверочных значения на одном имени, и оба должны существовать одновременно. Все интеграции ниже это учитывают – именно поэтому не удаляйте набор записей между двумя проверками.

Учитывайте время распространения

Записи проверки нужно около 30 секунд, чтобы дойти до серверов имён, поэтому 30-секундное ожидание не оставляет запаса – мы видели, как проверка падала с NXDOMAIN. Дайте удостоверяющему центру минимум 60 секунд: плагин certbot и lego по умолчанию ждут 60, а для acme.sh и CLI-хука время задаёте вы.

acme.sh

acme.sh – ACME-клиент на чистом shell. Наш DNS-хук пока не входит в релизы acme.sh, поэтому перед первым запуском положите его в ~/.acme.sh/dnsapi/: curl -fsSL https://get.nexdns.ru/acme/dns_nexdns.sh -o ~/.acme.sh/dnsapi/dns_nexdns.sh.

Выпуск сертификата

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export NEXDNS_Api="https://api.nexdns.ru/v1"
acme.sh --issue --server letsencrypt --dns dns_nexdns \
    --dnssleep 60 \
    -d example.com -d '*.example.com'

Токен сохраняется в ~/.acme.sh/account.conf после первого запуска, поэтому при продлении экспортировать его повторно не нужно.

Продление

Продление происходит автоматически через cron. Для принудительного продления:

acme.sh --renew -d example.com

Клиент lego и Traefik

lego – ACME-клиент на Go, на котором работает и автоматическое управление сертификатами в Traefik. Провайдер входит в lego начиная с версии 5.4.0.

Выпущенный провайдер всегда обращается к тому адресу API, который вкомпилирован в него, и не принимает настройку URL, поэтому с этим экземпляром он не работает. Для wildcard-сертификатов здесь используйте плагин certbot или CLI-хук ниже – они принимают адрес API этого экземпляра.

Клиент certbot

certbot – официальный клиент Let's Encrypt. Используйте плагин DNS-аутентификации NexDNS для автоматической проверки DNS-01.

Установка плагина

Установите плагин из PyPI или воспользуйтесь Docker-образом ниже – он уже включает плагин.

pip install certbot-dns-nexdns

Создание файла учётных данных

Создайте файл ~/.nexdns/certbot-credentials.ini с вашим API-токеном:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
dns_nexdns_api_url = https://api.nexdns.ru/v1

Ограничьте права доступа к файлу:

chmod 600 ~/.nexdns/certbot-credentials.ini

Выпуск сертификата

certbot certonly \
    --authenticator dns-nexdns \
    --dns-nexdns-credentials ~/.nexdns/certbot-credentials.ini \
    -d example.com \
    -d '*.example.com'

Использование с Docker

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    nexdns/certbot certonly \
        --non-interactive --agree-tos --email admin@example.com \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d example.com \
        -d '*.example.com'

CLI-хук

Если ваш ACME-клиент поддерживает ручные DNS-хуки, вы можете использовать CLI NexDNS в качестве скрипта-хука. Это работает с любым клиентом, поддерживающим параметры --manual-auth-hook и --manual-cleanup-hook (например, certbot в ручном режиме).

nexdns auth token nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
    --api-url https://api.nexdns.ru/v1

certbot с CLI-хуком

certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "nexdns acme hook --action create && sleep 60" \
    --manual-cleanup-hook "nexdns acme hook --action delete" \
    -d example.com \
    -d '*.example.com'

Хук считывает переменные окружения CERTBOT_DOMAIN и CERTBOT_VALIDATION, установленные certbot, и автоматически создаёт или удаляет TXT-запись _acme-challenge.

Перед использованием хуков CLI должен быть аутентифицирован. Выполните nexdns auth token nxd_xxx или установите переменную окружения NEXDNS_TOKEN.