Как сгенерировать CSR на Heroku

Этот учебник показывает вам как сгенерировать CSR (запрос на подпись сертификата) для Heroku с помощью OpenSSL и как загрузить выданный сертификат с помощью Heroku CLI.

У Heroku нет встроенной формы CSR на самой платформе, поэтому запрос и соответствующий приватный ключ генерируются вне платформы (на вашем локальном компьютере с Linux, macOS или Windows либо в любой оболочке с доступным OpenSSL). После того как удостоверяющий центр выдаст сертификат, вы объединяете его с промежуточной цепочкой и загружаете через heroku certs:add.

Действительно ли вам нужен CSR на Heroku?

Для большинства приложений Heroku ответ — нет. Функция Heroku Automated Certificate Management (ACM) выпускает и автоматически обновляет бесплатный сертификат Let’s Encrypt для каждого пользовательского домена приложения, без необходимости генерировать CSR или следить за календарём продлений. ACM доступен на dyno-конфигурациях Eco, Basic, Standard и Performance. Если ACM подходит для вашего случая, включите её одной командой CLI:

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

Генерируйте CSR и используйте самостоятельно управляемый (сторонний) сертификат только в одном из следующих случаев:

• Вам нужен wildcard-сертификат. ACM выдаёт только Let’s Encrypt-сертификаты с одним именем для каждого пользовательского домена, а не *.example.com.
• Вам нужна проверка OV или EV. ACM поддерживает только DV.
• Ваша политика или контракт требует конкретный удостоверяющий центр, отличный от Let’s Encrypt.
• У вас уже есть действующий сертификат, и вы хотите повторно развернуть его на Heroku без перевыпуска.
• Вам нужен многодоменный (SAN) сертификат, охватывающий имена хостов, которые не все находятся в этом приложении Heroku.

Если ничего из перечисленного не применимо к вашему случаю, пропустите работу с CSR и используйте ACM. Сам процесс установки описан в нашем руководстве как установить SSL-сертификат на Heroku.

Основы SSL на Heroku, которые нужно знать перед генерацией CSR

Несколько особенностей платформы определяют, как должны выглядеть CSR и ключ:

• SNI используется по умолчанию. Каждое новое приложение использует Heroku SSL, который опирается на Server Name Indication, поэтому одна конечная точка Heroku может обслуживать несколько HTTPS-хостов со своими сертификатами. Устаревшее дополнение SSL Endpoint было признано устаревшим в 2021 году (новое подключение прекратилось 14 мая 2021 года; продукт полностью прекратил поддержку 18 октября 2021 года) и недоступно для новых приложений.
• Только RSA-ключи. SSL-стек Heroku принимает приватные ключи RSA (2048 бит или больше). Ключи ECDSA не поддерживаются при ручной загрузке сертификатов, поэтому генерируйте CSR с параметром -newkey rsa:2048 (или rsa:3072 / rsa:4096, если ваша политика требует более длинный ключ).
• Требуется полная цепочка PEM (fullchain). Heroku ожидает единый PEM-файл, в котором сначала идёт сертификат конечного объекта, а затем — объединённый пакет промежуточного центра сертификации. Сертификат только с листовым (leaf) элементом будет отклонён при загрузке.
• Незашифрованный приватный ключ. Ключ, загружаемый вместе с сертификатом, не может быть защищён паролем. Приведённая ниже команда OpenSSL использует параметр -nodes для записи ключа в незашифрованном виде PEM.
• Обязательное условие — пользовательский домен. Heroku не привяжет ни один сертификат (ACM или ручной) до тех пор, пока пользовательский домен не будет зарегистрирован в приложении через heroku domains:add и не будет направлен на соответствующую DNS-цель *.herokudns.com.

Генерация CSR для Heroku с помощью OpenSSL

Если вы уже сгенерировали CSR и получили подписанный сертификат от вашего удостоверяющего центра, переходите сразу к разделу Загрузка сертификата на Heroku. Есть два способа создать CSR для развёртывания на Heroku:

• Используйте генератор CSR SSL Dragon: он создаёт как CSR, так и соответствующий приватный ключ RSA прямо в вашем браузере по короткой форме, после чего вы вставляете CSR при оформлении заказа SSL.
• Сгенерируйте CSR самостоятельно с помощью OpenSSL, либо на своём локальном компьютере, либо в любой оболочке, где установлен OpenSSL. Ниже описан этот путь.

Шаг 1: Откройте оболочку с OpenSSL

OpenSSL поставляется с каждым современным дистрибутивом Linux и с macOS. В Windows установите его (см. наше руководство установка OpenSSL в Windows) и выполните команду в PowerShell или Command Prompt. Откройте терминал в любой папке, куда у вас есть права на запись: OpenSSL создаст там файлы CSR и ключа в виде обычного текста, и вы сможете перенести их с машины по завершении.

Шаг 2: Выполните команду OpenSSL

Выполните следующую команду в вашей оболочке. Замените yourdomain на ваш реальный домен (например, example.com):

openssl req -new -newkey rsa:2048 -nodes 
  -keyout yourdomain.key -out yourdomain.csr 
  -addext "subjectAltName = DNS:yourdomain.com,DNS:www.yourdomain.com"

Что делает каждый параметр:

• -new создаёт новый CSR.
• -newkey rsa:2048 генерирует новый 2048-битный приватный ключ RSA вместе с CSR. Используйте rsa:3072 или rsa:4096, если ваша политика требует более длинный ключ. Не переключайтесь на ECDSA: Heroku отклоняет ключи ECC при ручной загрузке.
• -nodes записывает ключ без пароля (в OpenSSL 3.x эквивалентный параметр — -noenc; работают оба). Heroku отклонит зашифрованный приватный ключ при выполнении heroku certs:add.
• -keyout и -out — это пути вывода для ключа и CSR.
• -addext «subjectAltName=DNS:…» напрямую встраивает альтернативные имена субъекта (SAN) (требует OpenSSL 1.1.1 или новее). Каждый современный браузер и удостоверяющий центр требует расширение SAN, даже для сертификатов с одним доменом, поэтому включите как основной домен (yourdomain.com), так и любой вариант с www, который вы планируете обслуживать на Heroku. Для wildcard-сертификата также укажите *.yourdomain.com.

Шаг 3: Заполните данные CSR

OpenSSL запрашивает у вас поля идентификации сертификата. Заполните их следующим образом:

• Country Name (страна): двухбуквенный код ISO страны, где официально зарегистрирована ваша организация (например, US).
• State or Province Name (штат или регион): полное название штата или региона (например, Nevada). Не сокращайте.
• Locality Name (город): название города (например, Las Vegas).
• Organization Name (название организации): юридическое наименование вашей организации. Для сертификата Domain Validation это поле не проверяется и может быть пропущено, но не просто нажимайте Enter: в этом случае OpenSSL подставит значение по умолчанию из своей конфигурации, а в стандартной конфигурации указано Internet Widgits Pty Ltd, что попадёт в ваш CSR. Введите одну точку (.), чтобы оставить поле действительно пустым.
• Organizational Unit Name (подразделение организации): признано устаревшим CA/Browser Forum, поэтому оставьте пустым.
• Common Name (общее имя): полное доменное имя (FQDN), которое вы хотите защитить, например www.yourdomain.com. Для wildcard-сертификата введите *.yourdomain.com. Common Name также должно присутствовать в списке SAN.
• Email Address (адрес электронной почты): действующий контактный адрес электронной почты (или оставьте пустым).
• A challenge password (контрольный пароль) и An optional company name (дополнительное название компании): оставьте оба поля пустыми. Нажмите Enter, чтобы пропустить.

OpenSSL создаёт два файла в текущей директории:

• yourdomain.csr: CSR, который вы отправляете в свой удостоверяющий центр.
• yourdomain.key: приватный ключ. Храните этот файл в тайне и делайте резервную копию; он снова понадобится вам при загрузке выданного сертификата на Heroku.

Шаг 4: Отправьте CSR в свой удостоверяющий центр

Откройте файл yourdomain.csr в любом текстовом редакторе и скопируйте весь блок, включая маркеры -----BEGIN CERTIFICATE REQUEST----- и -----END CERTIFICATE REQUEST-----. Вставьте его в поле CSR при оформлении заказа SSL.

Перед отправкой вы можете проверить содержимое CSR с помощью нашего декодера CSR: он показывает Common Name, список SAN, тип и длину ключа, чтобы вы могли обнаружить опечатки до того, как это сделает удостоверяющий центр.

Выполните шаги проверки, запрошенные удостоверяющим центром (через DNS, файл или электронную почту). После выдачи сертификата удостоверяющий центр отправит вам подписанный сертификат конечного объекта (обычно файл .crt) и пакет промежуточного центра сертификации (часто файл .ca-bundle). Продолжите с загрузкой, описанной ниже.

Загрузка сертификата на Heroku

Шаг 1: Зарегистрируйте свой пользовательский домен в приложении

Heroku не привяжет сертификат, пока пользовательский домен не будет зарегистрирован в приложении. В терминале, авторизованном в Heroku CLI, выполните:

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

Замените www.example.com на ваш домен, а your-app-name — на название вашего приложения Heroku. Повторите команду для любых дополнительных имён хостов (например, для голого корневого домена или второго поддомена). Команда возвращает уникальную для каждого домена DNS-цель, например quiet-fire-1234.herokudns.com: на этот адрес вы направите свой DNS-провайдер на шаге 4.

Шаг 2: Соберите файл fullchain PEM

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

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

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

Шаг 3: Загрузите сертификат с помощью Heroku CLI

Для совершенно новой установки загрузите файл fullchain PEM и соответствующий приватный ключ с помощью certs:add:

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

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

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

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

Если во время загрузки вы видите ошибку Internal server error, почти всегда это означает, что Heroku CLI на вашей машине устарел. Выполните heroku update и попробуйте снова. Если ошибка не исчезает, убедитесь, что файл сертификата представляет собой полную цепочку (fullchain) в формате PEM (сначала конечный объект, затем промежуточные), а приватный ключ — это ключ RSA, соответствующий отправленному вами CSR.

Шаг 4: Направьте DNS на цель Heroku DNS

Выведите список ваших доменов и скопируйте DNS-цель, которую Heroku вернул для каждого из них:

heroku domains -a your-app-name

У вашего DNS-провайдера создайте по одной записи для каждого домена:

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

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

Проверка CSR и развёрнутого сертификата

Перед отправкой CSR декодируйте его локально, чтобы подтвердить Common Name, список SAN, тип и длину ключа:

openssl req -in yourdomain.csr -noout -text

Или вставьте CSR в наш декодер CSR, чтобы получить ту же информацию прямо в браузере.

После загрузки убедитесь, что сертификат установлен и обслуживает трафик. Из командной строки:

heroku certs:info -a your-app-name

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