Настройка web.config для Umbraco и Let's Encrypt SSL: Полное руководство

Конфигурация web.config для обслуживания файлов .well-known/acme-challenge как статических файлов в Umbraco включает добавление определенных правил перезаписи и настроек зарезервированных путей для обхода системы маршрутизации Umbraco при запросах на проверку от Let’s Encrypt.

Содержание

• Понимание проблемы
• Требования к конфигурации web.config
• Пошаговое руководство по реализации
• Устранение распространенных проблем
• Альтернативные решения
• Тестирование вашей конфигурации

Понимание проблемы

По умолчанию система маршрутизации CMS Umbraco перехватывает все запросы, включая запросы к путям без расширений, таким как /.well-known/acme-challenge/. Когда Let’s Encrypt пытается проверить право собственности на домен, обращаясь к файлу проверки, Umbraco пытается обработать запрос через свою систему контента вместо того, чтобы обслуживать его как статический файл, что приводит к ошибкам 404.

Как объясняется в обсуждении на Stack Overflow, “Umbraco пытается обработать этот URL через свою систему маршрутизации CMS вместо того, чтобы обслуживать его как статический файл”. Это поведение предотвращает успешную проверку права собственности на домен со стороны Let’s Encrypt.

Требования к конфигурации web.config

Для решения этой проблемы необходимо изменить файл web.config, добавив два ключевых компонента:

1. Конфигурация зарезервированных путей

Добавьте путь .well-known в список зарезервированных путей Umbraco:

<configuration>
  <appSettings>
    <add key="umbracoReservedPaths" value="~/umbraco,~/install,~/well-known" />
  </appSettings>
</configuration>

Это указывает Umbraco обойти свою систему маршрутизации для каталога .well-known.

2. Правила перезаписи IIS

Добавьте правила URL перезаписи для обеспечения обслуживания статических файлов:

<system.webServer>
  <rewrite>
    <rules>
      <!-- Это правило должно быть первым, чтобы разрешить доступ Let's Encrypt -->
      <rule name="Allow ACME Challenge" stopProcessing="true">
        <match url="\.well-known/acme-challenge/.*" />
        <action type="None" />
      </rule>
      
      <!-- Опционально: Перенаправление HTTP на HTTPS, за исключением проверки ACME -->
      <rule name="Redirect HTTP to HTTPS" stopProcessing="true">
        <match url="(.*)" />
        <conditions>
          <add input="{HTTPS}" pattern="off" ignoreCase="true" />
          <add input="{REQUEST_URI}" negate="true" pattern="^/.well-known/acme-challenge" />
        </conditions>
        <action type="Redirect" url="https://{HTTP_HOST}/{R:0}" redirectType="Permanent" />
      </rule>
    </rules>
  </rewrite>
  
  <!-- Опционально: Конфигурация MIME-типов -->
  <staticContent>
    <remove fileExtension="." />
    <mimeMap fileExtension="." mimeType="application/octet-stream" />
  </staticContent>
</system.webServer>

Пошаговое руководство по реализации

Шаг 1: Доступ к файлу Web.config

Через Plesk:

1. Перейдите в настройки хостинга вашего домена
2. Откройте “Файловый менеджер”
3. Перейдите в корневую каталог сайта
4. Найдите и отредактируйте web.config

Шаг 2: Добавление зарезервированных путей

Найдите раздел <appSettings> и добавьте ключ umbracoReservedPaths, если он отсутствует:

<appSettings>
  <add key="umbracoReservedPaths" value="~/umbraco,~/install,~/well-known" />
</appSettings>

Примечание: Существующее значение может уже содержать другие пути. Просто добавьте ~/well-known к существующему значению.

Шаг 3: Добавление правил перезаписи

Добавьте полный раздел правил перезаписи внутри <system.webServer>:

<system.webServer>
  <rewrite>
    <rules>
      <rule name="Allow ACME Challenge" stopProcessing="true">
        <match url="\.well-known/acme-challenge/.*" />
        <action type="None" />
      </rule>
    </rules>
  </rewrite>
</system.webServer>

Шаг 4: Сохранение и тестирование

1. Сохраните файл web.config
2. Дождитесь перезапуска пула приложений IIS (происходит автоматически)
3. Попробуйте снова обновить сертификат Let’s Encrypt

Устранение распространенных проблем

Проблема: Ошибки 404 продолжаются после настройки

Если вы продолжаете получать ошибки 404:

1. Проверьте порядок правил: Правило проверки ACME должно быть первым в разделе правил перезаписи
2. Проверьте синтаксис пути: Убедитесь, что шаблон соответствия правильный: \.well-known/acme-challenge/.*
3. Проверьте доступ к статическим файлам: Создайте тестовый файл вручную в /.well-known/acme-challenge/test.txt и попробуйте получить к нему прямой доступ

Проблема: Ошибки сервера 500

Как упоминается в обсуждении форума Umbraco, ошибки web.config в папке .well-known могут вызывать проблемы. Убедитесь, что ваш web.config правильно отформатирован как XML.

Проблема: Особенности Plesk

В средах Plesk вам также может потребоваться:

1. Отключить дружественные URL: В Plesk → Домены → ваш домен → Настройки хостинга → отключите “Apache Web Server”, если используете nginx
2. Проверьте брандмауэр Plesk: Убедитесь, что брандмауэр Plesk не блокирует доступ к путям .well-known
3. Проверьте права доступа к файлам: Убедитесь, что у пользователя IIS_IUSRS или соответствующего пользователя есть права на чтение файлов проверки

Альтернативные решения

Решение 1: Подход с использованием библиотеки медиафайлов

Как указано в документации Umbraco, вы можете обслуживать требуемый файл с помощью библиотеки медиафайлов Umbraco:

1. Перейдите в раздел Медиа в бэкенде Umbraco
2. Создайте папку с именем .well-known
3. Создайте вложенную папку acme-challenge
4. Загрузите файл проверки в это место
5. Добавьте правила перезаписи для маршрутизации запросов к медиаэлементу

Решение 2: Создание физических файлов

Некоторые пользователи успешно создают файлы проверки вручную:

1. Создайте физические папки: /.well-known/acme-challenge/
2. Создайте файл проверки в точном месте
3. Установите соответствующие права доступа к файлам
4. Используйте правила перезаписи для обеспечения статического обслуживания

Тестирование вашей конфигурации

Перед попыткой обновления Let’s Encrypt протестируйте вашу конфигурацию:

1. Создание тестового файла вручную:

   bash

   # Создание тестового файла
   echo "test-content" > /well-known/acme-challenge/test.txt
   

2. Прямой доступ по URL: Посетите https://ваш-домен.com/.well-known/acme-challenge/test.txt в вашем браузере

3. Тест с помощью curl:

   bash

   curl -I https://ваш-домен.com/.well-known/acme-challenge/test.txt
   

4. Ожидаемый ответ: Вы должны получить ответ 200 OK с тестовым содержимым

5. Тест Let’s Encrypt: Используйте среду тестирования Let’s Encrypt для тестирования без ограничений по скорости:

   bash

   certbot certonly --staging --manual -d ваш-домен.com
   

Источники

1. Umbraco 8 plus AppService AcmeBot Let’s Encrypt - Предоставляет основную конфигурацию web.config для интеграции Umbraco и Let’s Encrypt
2. Azure Let’s Encrypt extension cannot access .well-known/acme-challenge in Umbraco app - Объясняет основную проблему и подход к решению
3. Let’s Encrypt with Umbraco – serving static, extensionless URLs within an Umbraco installation - Подробное объяснение проблемы и различных подходов к решению
4. Umbraco site on Plesk ignores .well-known/acme-challenge for Let’s Encrypt validation - Специфично для устранения неполадок в среде Plesk
5. Rewrite rules | Umbraco Cloud - Официальная документация по правилам перезаписи URL для Umbraco
6. How to correctly run your website via HTTPS | uSkinned - Дополнительные примеры правил перезаписи для перенаправления HTTPS с сохранением доступа ACME

Заключение

Успешная настройка Umbraco для обслуживания файлов .well-known/acme-challenge как статического контента требует двух ключевых изменений в вашем web.config:

1. Добавьте ~/well-known в umbracoReservedPaths, чтобы предотвратить перехват этих запросов системой маршрутизации Umbraco
2. Реализуйте правильные правила перезаписи IIS для обеспечения обслуживания статических файлов для проверки Let’s Encrypt

Помните:

• Размещайте правило проверки ACME первым в разделе правил перезаписи
• Тестируйте вашу конфигурацию вручную перед попыткой обновления Let’s Encrypt
• Будьте готовы к особенностям Plesk, которые могут потребовать дополнительного устранения неполадок

Эти изменения конфигурации позволят Let’s Encrypt успешно проверять право собственности на домен, обращаясь к файлам проверки напрямую как к статическому контенту, обходя систему маршрутизации контента Umbraco.