Как установить SSL-сертификат на Heroku

Это руководство показывает вам, как установить SSL-сертификат на Heroku. Оно охватывает оба способа, которыми Heroku сегодня завершает TLS-соединения: Automated Certificate Management (ACM), который предоставляет и продлевает бесплатные сертификаты Let’s Encrypt за вас, и ручную загрузку стороннего сертификата через панель управления или Heroku CLI.

Прежде чем начать, стоит узнать несколько вещей. Устаревшее дополнение Heroku SSL Endpoint (платный продукт за $20/месяц) было выведено из эксплуатации в 2021 году и больше не может быть предоставлено на новых приложениях. Каждое новое HTTPS-развертывание использует Heroku SSL, который опирается на расширение SNI (Server Name Indication) и включен бесплатно в любой платный тариф dyno. Бесплатные dynos были упразднены 28 ноября 2022 года, поэтому вам нужен тариф Eco, Basic, Standard или Performance, чтобы подключить пользовательский домен и обслуживать HTTPS.

Создание CSR (для вручную загружаемых сертификатов)

Если вы уже создали CSR и получили выданный сертификат от вашего центра сертификации, перейдите к разделу Установка SSL-сертификата на Heroku.

CSR нужен только в том случае, если вы покупаете сторонний сертификат для ручной загрузки. Если вы планируете использовать ACM, вы можете полностью пропустить этот раздел: ACM выдает сертификат за вас, и нет необходимости отправлять CSR.

CSR (Certificate Signing Request, запрос на подпись сертификата) — это текстовый блок, который вы отправляете центру сертификации при оформлении заказа. Он содержит данные вашего домена и организации, а также открытый ключ, для которого будет выдан сертификат. Heroku не создает CSR непосредственно на платформе, поэтому запрос генерируется вне ее. У вас есть два варианта:

• Используйте CSR Generator от SSL Dragon, который создает CSR и соответствующий закрытый ключ на основе короткой формы.
• Сгенерируйте запрос локально с помощью OpenSSL, следуя нашему руководству как создать CSR для Heroku.

Откройте получившийся файл .csr в любом текстовом редакторе и скопируйте весь блок, включая маркеры ——BEGIN CERTIFICATE REQUEST—— и ——END CERTIFICATE REQUEST——, затем вставьте его при оформлении заказа в SSL Dragon. Дождитесь, пока CA проверит и выдаст сертификат (от нескольких минут для DV до нескольких рабочих дней для OV/EV), и продолжите установку, описанную ниже.

Установка SSL-сертификата на Heroku

Heroku предлагает два пути к HTTPS. Выберите тот, который соответствует способу получения вашего сертификата:

• ACM (рекомендуется для большинства приложений). Heroku выдает, устанавливает и автоматически продлевает бесплатный сертификат Let’s Encrypt для каждого пользовательского домена приложения. Не нужно загружать файлы или отслеживать сроки продления. Доступно на тарифах Eco, Basic, Standard и Performance.
• Ручная загрузка. Используйте этот вариант, если вам нужен конкретный сторонний сертификат (например, продукт Organization Validated или Extended Validation, либо wildcard-сертификат от CA, отличного от Let’s Encrypt). Вы загружаете сертификат и закрытый ключ самостоятельно через панель управления или CLI.

Шаг 1. Добавьте пользовательский домен в приложение

Heroku не предоставит ни один сертификат (ACM или ручной) до тех пор, пока ваш пользовательский домен не будет зарегистрирован в приложении. В терминале с повышенными правами выполните:

heroku domains:add www.example.com -a your-app-name

Замените www.example.com на ваш домен, а your-app-name — на название вашего приложения Heroku. Повторите команду для каждого дополнительного имени хоста (например, для корневого домена или второго поддомена). Вы также можете добавить домен из панели управления в разделе Settings > Domains and certificates > Add domain.

Для каждого добавленного домена возвращается уникальный DNS target, например quiet-fire-1234.herokudns.com. Это значение понадобится вам при обновлении DNS на шаге 3.

Шаг 2. Получите сертификат

Вариант А: ACM (бесплатный, автоматически продлеваемый Let’s Encrypt)

Включите ACM для приложения через CLI:

heroku certs:auto:enable -a your-app-name

Heroku начинает выдавать сертификат Let’s Encrypt для каждого пользовательского домена приложения. Чтобы отслеживать процесс и подтвердить статус, выполните:

heroku certs:auto -a your-app-name

Вы также можете включить ACM из панели управления: откройте приложение, перейдите в Settings > Domains and certificates, нажмите Configure SSL, выберите Automated Certificate Management, затем Continue. После того как DNS настроен (шаг 3), ACM завершает проверку домена, и сертификат вступает в силу. Продление происходит автоматически примерно за месяц до истечения срока действия.

Вариант Б: ручная загрузка стороннего сертификата

CA присылает три файла в ваш почтовый ящик:

• Конечный сертификат, обычно с расширением .crt (в формате PEM).
• Пакет CA (промежуточные сертификаты), часто с расширением .ca-bundle.
• Закрытый ключ, сгенерированный вместе с CSR (файл .key).

Heroku ожидает получить один PEM-файл, содержащий конечный сертификат, за которым следуют промежуточные (полная цепочка сертификатов, fullchain). В Linux или macOS объедините их с помощью cat:

cat yourcertificate.crt bundle.ca-bundle > server.crt

В Windows откройте оба файла в обычном текстовом редакторе (Notepad++ или VS Code, но не Word) и вставьте содержимое файла .ca-bundle после содержимого файла .crt, именно в таком порядке, без пустой строки между блоками. Сохраните объединенный файл как server.crt.

Загрузите полную цепочку и закрытый ключ с помощью Heroku CLI:

heroku certs:add server.crt server.key -a your-app-name

Если вы заменяете существующий сертификат в приложении (например, при продлении), используйте вместо этого команду certs:update, чтобы Heroku сохранил тот же DNS target:

heroku certs:update server.crt server.key -a your-app-name

Предпочитаете панель управления? Откройте приложение, перейдите в Settings > Domains and certificates, нажмите Configure SSL, выберите Manually, затем перетащите объединенный файл server.crt в поле сертификата, а файл .key — в поле закрытого ключа. Нажмите Next и подтвердите.

Если при загрузке появляется ошибка Internal server error, скорее всего, ваш локальный Heroku CLI устарел. Обновите его командой heroku update и попробуйте снова. Heroku также требует ключи RSA; ключи ECDSA в настоящее время не поддерживаются для ручной загрузки.

Шаг 3. Направьте DNS на DNS target Heroku

Независимо от способа получения сертификата, он вступит в силу только после того, как DNS вашего пользовательского домена будет указывать на Heroku. Просмотрите список ваших доменов и скопируйте DNS target, который вернул Heroku:

heroku domains -a your-app-name

Вы увидите значение вроде quiet-fire-1234.herokudns.com рядом с каждым доменом. У вашего DNS-провайдера создайте одну запись для каждого домена:

• Поддомен (например, www.example.com): создайте запись CNAME, указывающую на DNS target Heroku.
• Корневой домен / apex (например, example.com): CNAME не допускается на apex-домене согласно спецификации DNS, поэтому используйте запись ALIAS, ANAME или сглаженный CNAME (flattened-CNAME) (точное название зависит от вашего DNS-провайдера), указывающую на тот же DNS target Heroku. Если ваш DNS-провайдер не поддерживает ни один из этих вариантов, разместите DNS у того, кто поддерживает (Cloudflare, DNSimple, Route 53, NS1, easyDNS и т.д.).

Не направляйте DNS на your-app-name.herokuapp.com или на любой хост *.herokussl.com: ACM не сможет проверить сертификат через них, и ручная привязка также не будет работать корректно. Всегда используйте персональный для домена DNS target, назначенный Heroku.

Изменения DNS могут распространяться от нескольких минут до нескольких часов. Как только Heroku увидит обновленную запись, ACM автоматически завершит проверку (или ваш вручную загруженный сертификат начнет обслуживать трафик).

Шаг 4. Проверьте, что сертификат активен

Подтвердите установку через CLI:

heroku certs:info -a your-app-name

В выводе перечислены сертификат, выдавший его CA, срок действия и домены, которые он охватывает. Затем откройте ваш сайт по https:// в браузере и убедитесь, что значок замка присутствует, а также выполните более глубокую внешнюю проверку с помощью нашего SSL Checker, чтобы подтвердить, что цепочка сертификатов полная, а протоколы настроены правильно.

Часто задаваемые вопросы