Локальный HTTPS в dev-окружении — простая настройка

Иногда в процессе веб-разработки требуется безопасное окружение в браузере, то есть HTTPS. Удобный способ сделать это — установить локальный УЦ и автоматизировать выдачу сертификатов на любые поддомены lcl.host и localhost. Это более функциональная и удобная альтернатива самоподписанным сертификатам.

Для установки локального УЦ есть инструменты lcl.host и mkcert, которые помогают быстро настроить и использовать HTTPS в dev-окружении.

Если mkcert относительно хорошо известен, то lcl.host появился только в марте 2024 года. В некотором отношении это более удобный инструмент — он настраивает HTTPS в интерактивном режиме консоли в несколько нажатий кнопки (об этом ниже).

HTTPS в dev-окружении

В документации lcl.host поясняется, что локальный HTTPS может пригодиться при разработке следующих сервисов:

• Публичные веб-сайты и приложения. В этом случае в продакшне есть публичный сертификат, а мы хотим имитировать эту среду локально.
• SaaS. Сервисы в интернете, например, SaaS-проект на Ruby on Rails.
• Микросервисы. Например, приложение на React обращается к отдельному API бэкенда, устанавливая cookies и делая API-запросы.

Локальный HTTPS решает ряд проблем в реальной веб-разработке:

• Смешанный контент. В идеальном мире всё содержимое передаётся по HTTPS. К сожалению, в реальном мире защищённая веб-страница может запрашивать незащищённое содержимое по HTTP. Поэтому нужно добавить HTTPS в локальную среду, чтобы имитировать смешанный контент в продакшне.
• Ошибки CORS. Когда веб-страница загружает содержимое из нескольких источников, контекст безопасности браузера может измениться, что приведёт к ошибке CORS. Сохраняя в браузере тот же контекст безопасности, что и в продакшне, можно локально воспроизвести и отладить проблемы CORS.
• HTTP/2. HTTP/2 и HTTP/3 требуют (или не позволяют избежать) использования TLS.
• Безопасные куки. Как правило, браузеры работают с куками на localhost так же, как и в продакшне, за исключением безопасных куков (с атрибутом Secure, который ограничивает область применения куки). Чтобы поведение браузеров было одинаковым, нужно использовать HTTPS в локальной среде аналогично продакшну.
• OAuth и безопасные сторонние эндпоинты. Многие внешние организации требуют HTTPS для эндпоинтов даже в локальной разработке.
• Приложения и маркетплейсы на локальном хосте. Некоторые инструменты, которые запускают веб-сервер на локальном порту и открываются в браузере через http://localhost:[PORT], иногда требуют HTTPS, также как маркетплейсы вроде Heroku, Slack и AWS (при разработке приложений для маркетплейса).
• Требования к инструментам. Некоторые dev-инструменты для корректной работы требуют HTTPS.

Сравнение с самоподписанными сертификатами

Обычно в dev-окружении используются самоподписанные сертификаты, но им присущи некоторые недостатки:

• Все члены команды должны вручную создавать (и пересоздавать) свои собственные самоподписанные сертификаты.
• Самоподписанные сертификаты нужно вручную добавлять в каждое хранилище доверия в системе.
• Домены app.localhost работают не везде, поэтому для небраузерных клиентов (например, curl) требуются записи в /etc/hosts или DNS-сервер разработки.
• Запуск приложений в локальных контейнерах требует постоянного обновления сертификатов и хранилища доверия.

Система lcl.host с приватным УЦ решает эти проблемы, потому что устанавливается в системные каталоги доверенных сертификатов, обеспечивая универсальность работы в разных средах и внутри, вне и даже между контейнерами, а поддержка ACME позволяет настраивать автоматическую выдачу и продление сертификатов. Имена хостов работают повсюду, без какой-либо настройки. Здесь тот же безопасный контекст браузера, что и в продакшне, без причуд браузера в контексте localhost.

Настройка программы не требует знания формата сертификатов и принципов их работы.

Чтобы настроить HTTPS в разработке, нужно установить инструментарий Anchor CLI, запустить anchor lcl и просто следовать инструкциям.

$ brew install anchordotdev/tap/anchor $ anchor lcl

Под Windows нужно установить пакетный менеджер Chocolatey, а уже из него — Anchor и lcl:

> choco install anchor --version=0.0.22 > anchor lcl

После запуска программы большинство инструкций для настройки HTTPS-окружения — это нажимать Enter, вводить имена доменов, скопировать код в окно браузера и т. д., как в базовом примере:

~/nextjs-app $ anchor lcl                                                                                                          | Let's set up HTTPS in your local development environment!                                                                        |                                                                                                                                  | lcl.host (made by the team at Anchor) is a fast and completely free                                                              | way to add HTTPS to local applications & services.                                                                               |                                                                                                                                  | Once setup is finished you'll have a secure context in your browsers                                                             | and local system so you can run HTTPS locally.                                                                                   # System Configuration `anchor lcl config`                                                                                             | Before issuing HTTPS certificates for your local applications, we need                                                           | to configure your browsers and OS to trust your personal certificates.                                                           |                                                                                                                                  | We'll start a local diagnostic webserver to guide you through                                                                    | the system configuration process.                                                                                                - Scanned local configuration and status.                                                                                          - Entered hi-ankydotdev.lcl.host domain for lcl.host diagnostic certificate.                                                       | Now it's time to create your application's resources in Anchor.dev and start                                                     | provisioning HTTPS certificates for your development environment                                                                 - Created hi-ankydotdev [hi-ankydotdev.lcl.host, hi-ankydotdev.localhost] diagnostic server resources on Anchor.dev.               - Great, http://hi-ankydotdev.lcl.host:4433 works as expected (without HTTPS)                                                      | Next, we'll add your personal CA certificates to your system's trust stores                                                      | This may require sudo privileges. Here's why:                                                                                    | https://lcl.host/why-sudo                                                                                                        - Compared local stores to expected CA certificates: need to install 2 missing certificates.                                       - Updated System (MacOS Keychain): installed ankydotdev/localhost - AnchorCA [RSA, ECDSA]                                          - Updated Network Security Services (NSS): installed ankydotdev/localhost - AnchorCA [RSA, ECDSA]                                  - Updated Homebrew OpenSSL (ca-certificates): installed ankydotdev/localhost - AnchorCA [RSA, ECDSA]                               | Before we move on, let's make sure your system is configured properly                                                            | by trying out HTTPS with our local diagnostic webserver.                                                                         - Success! https://hi-ankydotdev.lcl.host:4433 is encrypted and HTTPS is working as expected                                   # Application Setup `anchor lcl setup`                                                                                                 | Start by choosing the server type of your local application so we can generate                                                   | setup instructions for your specific application type.                                                                           - Scanned current directory.                                                                                                       - Entered javascript application type                                                                                              - nextjs-app application name.                                                                                                     - Entered nextjs-app domain for local application development                                                                      | Now it's time to create your application's resources in Anchor.dev and start                                                     | provisioning HTTPS certificates for your development environment                                                                 - Created nextjs-app [nextjs-app.lcl.host, nextjs-app.localhost] javascript server resources on Anchor.dev.                    # Provision Certificate `anchor lcl mkcert`                                                                                            - Provisioned certificate for [nextjs-app.lcl.host, nextjs-app.localhost].                                                         - Wrote certificate to ./nextjs-app.lcl.host+1-cert.pem                                                                            - Wrote chain to ./nextjs-app.lcl.host+1-chain.pem                                                                                 - Wrote key to ./nextjs-app.lcl.host+1-chain.pem                                                                                   | You can use these certificate files to manually configure your application and start                                             | using HTTPS in your development environment.                                                                                 # Next Steps                                                                                                                           | Now that you have local HTTPS setup, let's automate the certificate provisioning process                                         | so you never have to manually provision future certificates.                                                                     |                                                                                                                                  | We've generated a setup guide for your application on Anchor.dev with instructions on                                            | how to automate certificate provisioning inside your application.                                                                - Opened https://anchor.dev/ankydotdev/services/nextjs-app/guide.

lcl.host можно сравнить с инструментом mkcert, который тоже предназначен для создания локально доверенных dev-сертификатов с произвольными именами. Он тоже создаёт локально приватный удостоверяющий центр уже в процессе установки:

$ mkcert -install Created a new local CA ? The local CA is now installed in the system trust store! ⚡️ The local CA is now installed in the Firefox trust store (requires browser restart)! ?  $ mkcert example.com "*.example.com" example.test localhost 127.0.0.1 ::1  Created a new certificate valid for the following names ?  - "example.com"  - "*.example.com"  - "example.test"  - "localhost"  - "127.0.0.1"  - "::1"  The certificate is at "./example.com+5.pem" and the key at "./example.com+5-key.pem"

Как написано в документации, lcl.host сочетает в себе управляемый приватный УЦ Anchor, DNS-зону для разрешения поддоменов в локальной системе и утилиту командной строки Anchor CLI для управления локальными хранилищами доверия. Нужно заметить, что управляемый УЦ Anchor — это уже платная услуга. Отличие lcl.host от инструмента mkcert том, что шаги по настройке в lcl.host максимально автоматизированы в интерактивном консольном UI (см. пример выше).

В любом случае, локальный УЦ — более функциональная альтернатива самоподписанным сертификатам в dev-окружении.