Настройка Let's Encrypt для Azure Web App

Коротко о содержании

• Что такое Let’s Encrypt и почему он полезен
• Необходимые компоненты в Azure
• Создание Storage Account для WebJobs
• Настройка Service Principal для автоматизации
• Установка и конфигурация расширения Let’s Encrypt
• Типичные проблемы и способы их решения
• Чек-листы, сценарии тестирования и критерии приёмки

Что такое Let’s Encrypt?

Let’s Encrypt — это бесплатный и автоматизированный центр сертификации (CA). Он позволяет автоматически выпускать сертификаты TLS/SSL, чтобы переводить сайт с HTTP на HTTPS. Сертификаты Let’s Encrypt действуют 90 дней. Короткий срок служит стимулом к автоматизации продления, а не к ручной ротации сертификатов.

Преимущество: бесплатность и простая автоматизация. Ограничение: короткий срок действия (90 дней) — значит, вам нужно настроить автоматическое обновление.

Важно: термин “ACME” (Automatic Certificate Management Environment) — это протокол, который используют Let’s Encrypt и клиентские инструменты для валидации доменов и выдачи сертификатов.

Необходимые условия

Перед началом убедитесь, что у вас есть:

• Активная подписка Azure.
• Веб-приложение в Azure App Service (стек не важен: .NET, Node, PHP и т.д.).
• Пользовательский DNS‑запись (A или CNAME), указывающая на ваш Web App.
• Права на создание Service Principal или доступ администратора для делегирования ролей.

Рекомендация: храните App Service и App Service Plan в одном Resource Group — так меньше путаницы, но это не строго обязательно.

Шаг 1: Storage Account для WebJobs

Для автоматического продления сертификатов используется WebJob, который сохраняет временные данные и токены в Azure Storage. Создайте Storage Account типа “Storage” или “StorageV2”. Не используйте BlobStorage — он не подходит для этой задачи.

После создания Storage Account добавьте в настройки приложения (Application Settings) две строки подключения:

• AzureWebJobsDashboard
• AzureWebJobsStorage

Пример строки подключения (формат):

DefaultEndpointsProtocol=https;AccountName=[youraccount];AccountKey=[yourkey];

Совет: скопируйте значение из Access Keys в разделе Storage Account → Access keys.

Шаг 2: Автоматизация через Service Principal

Для того чтобы расширение могло создавать/назначать сертификаты и привязывать их к App Service, нужно создать сервисный принципал в Azure AD и дать ему роль Contributor на нужный Resource Group.

1. Откройте Azure Active Directory → App registrations.
2. Создайте новое приложение (регистрацию приложения). Пример интерфейса:

3. В разделе Certificates & secrets создайте новый client secret и сохраните его в безопасном месте. После создания вы не сможете посмотреть значение снова.
4. Скопируйте Client ID (Application ID) и Tenant ID из Overview.
5. Перейдите в Resource Group, где находятся App Service и (если нужно) App Service Plan. Выберите Access control (IAM) → Add role assignment.
6. Выберите роль “Contributor” и назначьте её на созданный Service Principal.

Пояснение терминов в одной строке:

• Service Principal — учётная запись для приложения в Azure AD, позволяющая выдавать ему права.
• Contributor — роль, дающая возможность управлять ресурсами (кроме назначения ролей).

Безопасная практика: ограничьте область действия роли на уровень Resource Group, а не на подписку, если это возможно.

Шаг 3: Установка расширения Let’s Encrypt и конфигурация

Установите расширение Azure Let’s Encrypt (SJKP) через Site Extensions в Advanced Tools (Kudu). Для этого откройте App Service → Advanced Tools → Go → Site Extensions → Найдите “Let’s Encrypt” → Установите.

Далее откройте установленное расширение и заполните поля конфигурации:

• Tenant: Tenant ID Azure AD.
• ClientID: Application (client) ID из App Registrations.
• ClientSecret: ранее созданный secret.
• ResourceGroupName: имя Resource Group, где находится App Service.
• SubscriptionID: ID подписки, используемой для ресурсов.
• Update Application Settings: True (обязательно), чтобы запись конфигурации сохранилась как Application Settings и была доступна WebJob.
• ServicePlanResourceGroupName: если App Service Plan в другом Resource Group, укажите его имя, иначе оставьте как ResourceGroupName.

Когда все поля заполнены, расширение покажет обзор Certificates, SSL Bindings и custom domains. Выберите домены, для которых нужно получить сертификат, добавьте контактный email и запросите сертификат (Get Certificate).

Подсказки:

• Добавьте адрес электронной почты для уведомлений об истечении и ошибках.
• Убедитесь, что выбранный домен добавлен в Custom domains App Service.

Технические детали и почему всё это работает

Let’s Encrypt использует ACME и несколько типов проверки владения доменом. Одним из самых распространённых — HTTP‑01. В этом сценарии клиент (расширение) создаёт файл с токеном в каталоге /.well-known/acme-challenge/ на вашем веб‑сайте. Let’s Encrypt затем делает HTTP-запрос (не HTTPS) к http://yourdomain/.well-known/acme-challenge/ и проверяет содержимое.

Важно: проверка выполняется по HTTP. Поэтому принудительное перенаправление на HTTPS или правила в web.config, блокирующие доступ к /.well-known, помешают проверке.

Потенциальные проблемы и решения

1. Проблема: Let’s Encrypt не может получить доступ к http://yourdomain/.well-known/acme-challenge/

   • Причина: включено принудительное HTTPS, или правила в web.config/URL Rewrite блокируют доступ.
   • Решение: временно отключите принудительное HTTPS или добавьте исключение для /.well-known/acme-challenge/ в правилах перенаправления. Убедитесь, что публичный DNS указывает правильно.

2. Проблема: Не сохраняются настройки расширения после установки.

   • Причина: Update Application Settings установлен в False.
   • Решение: установите Update Application Settings в True и повторите конфигурацию.

3. Проблема: WebJob не запускается или перестаёт работать после перезапуска App Service.

   • Причина: неверные строки подключения AzureWebJobsStorage/AzureWebJobsDashboard.
   • Решение: проверьте строки подключения, убедитесь, что ключ доступа не истёк, Storage Account в том же регионе (рекомендуется).

4. Проблема: Ошибка авторизации при вызовах к Azure API.

   • Причина: Service Principal не имеет роли Contributor на нужной Resource Group.
   • Решение: назначьте роль Contributor на Resource Group с App Service и Service Plan.

5. Проблема: Сертификаты не продлеваются автоматически.

   • Возможные причины: WebJob не расписан, Service Principal лишён прав, строки подключения к Storage некорректны.
   • Проверьте: статус WebJob в App Service → WebJobs; логи в Kudu; наличие последних Application Settings.

Чек-лист перед запуском

• DNS записан и указывает на Web App.
• Custom domain добавлен в App Service.
• Storage Account создан (Storage или StorageV2).
• AzureWebJobsStorage и AzureWebJobsDashboard добавлены в Application Settings.
• Service Principal создан и имеет Client ID, Client Secret и Tenant ID.
• Service Principal назначен с ролью Contributor на нужный Resource Group.
• Расширение Let’s Encrypt установлено и настроено (Update Application Settings = True).
• Email для оповещений указан.

Ролевые обязанности (кто что делает)

• DevOps / Системный администратор:

  • Создаёт Storage Account.
  • Настраивает Application Settings.
  • Настраивает Service Principal и IAM.
  • Отслеживает WebJobs и логи Kudu.

• Разработчик:

  • Добавляет исключения в правила перенаправления, если нужно.
  • Проверяет работу приложения после установки сертификата.

• Менеджер по безопасности:

  • Проверяет, что секреты безопасно хранятся (Key Vault рекомендуется).
  • Убедится, что права ограничены по scope.

Мини-методология релиза (быстрый SOP)

1. Создать Storage Account и настроить Application Settings.
2. Создать Service Principal, сгенерировать Client Secret, записать Client ID и Tenant ID.
3. Назначить Service Principal роль Contributor на Resource Group.
4. Установить расширение Let’s Encrypt и заполнить поля конфигурации.
5. Проверить доступность http://yourdomain/.well-known/acme-challenge/ (временно отключить HTTPS).
6. Запросить сертификат, привязать SSL Binding и вернуть принудительное HTTPS.
7. Наблюдать за первым циклом обновления и проверить логи WebJob.

Критерии приёмки

• Сертификат получен и привязан к домену (HTTPS работает без предупреждений).
• WebJob для автоматического обновления запущен и имеет рабочий статус.
• Application Settings содержат правильные строки подключения и переменные расширения.
• После включения принудительного HTTPS сайт корректно обслуживает /.well-known/acme-challenge/ (исключения в правилах перенаправления настроены).
• Ответственные лица проинформированы и получили уведомления на email при ошибках.

Тест-кейсы и приёмочные проверки

1. Получение сертификата для одного домена — ожидаемый результат: 200 OK при https://mydomain/ и сертификат действителен.
2. Продление сертификата — имитация истечения: запустить WebJob вручную и убедиться в успешном обновлении.
3. Проверка доступа к /.well-known/acme-challenge/ — разместить тестовый файл и получить его по HTTP.
4. Поведение при включённом принудительном HTTPS — добавить правило исключения и проверить прохождение HTTP-01.

План отката и инцидентный runbook

Если после установки сертификата приложение стало недоступно:

1. Отключите SSL Binding в App Service → TLS/SSL settings.
2. Верните прежние Application Settings, если что-то сломалось.
3. Временно верните правила в web.config, обеспечивающие доступ к /.well-known, если они были обновлены.
4. Проверьте логи WebJob и Kudu для ошибок.
5. При необходимости откатите изменения через инфраструктурный код/ARM шаблон.

Модель принятия решений (Flowchart)

flowchart TD
  A[Начало] --> B{Custom domain добавлен?}
  B -- Да --> C{DNS корректен?}
  B -- Нет --> Z[Добавить домен в App Service]
  C -- Да --> D[Создать Storage Account]
  C -- Нет --> Y[Исправить DNS]
  D --> E[Создать Service Principal]
  E --> F[Назначить роль Contributor]
  F --> G[Установить расширение Let's Encrypt]
  G --> H[Запросить сертификат]
  H --> I{Проверка успешна?}
  I -- Да --> K[Включить HTTPS и мониторинг]
  I -- Нет --> J[Откат/траблшутинг]

Безопасность и конфиденциальность

• Секреты (ClientSecret, строки подключения) храните в Azure Key Vault и ограничьте доступ.
• Не давайте Service Principal лишних прав. Рекомендованный scope — Resource Group с App Service и Service Plan.
• Ведение логов: аудитируйте действия Service Principal и WebJob через Azure Monitor.

Советы по эксплуатации и мониторингу

• Настройте оповещения на случай неудачных попыток продления сертификата.
• Раз в месяц проверяйте логи WebJob и состояние сертификатов в портале.
• Рассмотрите автоматизацию хранения секретов в Key Vault и привязку к Managed Identity (если расширение поддерживает).

Когда этот подход не подходит

• Если у вас нет возможности публично открыть HTTP-эндпоинт для проверки (например, внутренние сети без публичного DNS) — HTTP-01 не сработает.
• В случаях строгих требований к срокам действия сертификатов (нужны много-летние OV/EV) — Let’s Encrypt не выдаёт такие сертификаты.

Краткое резюме

Let’s Encrypt для Azure App Service — это экономичное и автоматизируемое решение для TLS. Важные элементы: Storage Account для WebJobs, Service Principal с ролью Contributor, корректные Application Settings и расширение Let’s Encrypt. Главная трудность — обеспечить доступность /.well-known/acme-challenge/ по HTTP во время проверки.

Факт‑бокс:

• Срок действия сертификата Let’s Encrypt: 90 дней.
• Необходимые ресурсы: Storage (StorageV2), App Service, Service Principal.

Часто задаваемые вопросы (коротко):

• Нужно ли платить? Нет — сертификаты бесплатны.
• Как часто обновлять сертификаты? Процесс должен быть автоматизирован — каждые ~60–80 дней будет безопасно, но Let’s Encrypt требует обновления каждые 90 дней.

Контактная заметка: после настройки назначьте ответственного за мониторинг и убедитесь, что на почту приходят уведомления об ошибках продления.