Дополнительные сертификаты доверия для исходящих HTTPS (Node.js)

Материал для администраторов серверной версии Бипиума: при интеграциях отдельные компоненты системы на Node.js выполняют исходящие запросы по HTTPS. Если сервер отвечает сертификатом, цепочка которого не опирается на стандартные корневые центры, встроенные в Node.js, проверка TLS завершается ошибкой (например, UNABLE_TO_VERIFY_LEAF_SIGNATURE, unable to verify the first certificate).

Рекомендуемый способ — не отключать TLS, а явно добавить доверие: переменная окружения NODE_EXTRA_CA_CERTS и один файл PEM с полной цепочкой корней и промежуточных сертификатов (в т.ч. корпоративного УЦ).

Типовые ситуации

• Вызов внешнего API из сценария (действие «Веб-запрос»), у провайдера — цепочка на национальном или корпоративном УЦ (пример: GigaChat и требования к сертификатам).

• Вход по SSO: сервер Бипиума обращается к провайдеру OpenID Connect (например, Keycloak) по https://, TLS выдан УЦ заказчика — на сервере Бипиума нужна доверенная цепочка в PEM.

• Любой другой исходящий HTTPS из Node-компонента к узлу с «нестандартным» для Node доверием.

На каком сервисе платформы настраивать

Переменную NODE_EXTRA_CA_CERTS и путь к PEM задают тому сервису, в процессе которого выполняется проблемный исходящий HTTPS. Если оба контура обращаются к таким узлам — настройку дублируют отдельно для каждого процесса.

Переменная NODE_EXTRA_CA_CERTS

Как это работает

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

Node.js подмешивает их поверх встроенного набора корневых CA; проверка TLS остаётся включённой.

Официальное описание: Node.js — CLI, переменные окружения.

Безопасность: чего избегать в продуктивной среде

Не использовать по умолчанию глобальное отключение проверки TLS (NODE_TLS_REJECT_UNAUTHORIZED=0 и аналоги). Для продуктивной среды предпочтительно PEM + NODE_EXTRA_CA_CERTS.

Где задать переменную: config.env, Docker, операционная система

Итог один: переменная должна попасть в process.env процесса Node.js сервера Бипиума и/или bpm до того, как пойдут проблемные HTTPS-запросы. Удобные варианты:

1. Файл config.env (типовой способ для коробки)

• Сервер Бипиума при старте загружает config.env из рабочего каталога процесса (значения подмешиваются в окружение через dotenv).

• bpm (сервер исполнения процессов) читает свой отдельный config.env из своего рабочего каталога ( bpm/config.env). Переменная из config.env сервера Бипиума в процесс bpm не подставляется: для сценариев и «Веб-запроса» строку нужно добавить в config.env именно bpm (и при необходимости продублировать PEM в доступное для контейнера/каталога bpm место).

Добавьте в нужный файл строку (путь — абсолютный; в Docker — путь внутри контейнера, если PEM монтируется туда):

NODE_EXTRA_CA_CERTS=/полный/путь/к/цепочке.pem

На Windows в том же файле допустим путь вида C:\Bpium\certs\company-chain.pem. После правки config.env перезапустите соответствующий сервис (сервер Бипиума или bpm).

2. Docker Compose

Секция environment (как в примерах ниже) или env_file, указывающий на ваш config.env, если шаблон развёртывания так устроен — лишь бы переменная оказалась в окружении контейнера при старте.

3. Без config.env

Переменную можно задать в системных переменных Windows, в Environment= unit systemd, в скрипте запуска перед исполняемым файлом и т.п. — по смыслу то же, что уже описано в разделах про Windows и Linux.

Подготовка файла PEM

Шаг 1: Получить сертификаты

Запросите у провайдера интеграции или ИБ сертификаты корневого и при необходимости промежуточных удостоверяющих центров (открытая часть цепочки доверия для проверки TLS). Закрытый ключ для bundle не нужен и передавать его не следует.

Шаг 2: Собрать bundle

Создайте один файл .pem, внутри — несколько блоков подряд:

-----BEGIN CERTIFICATE-----
…
-----END CERTIFICATE-----

Шаг 3: Разместить файл

Сохраните файл в каталоге с подходящими правами доступа для пользователя или контейнера, от которого запускается Node.js.

Настройка в Docker

Имена сервисов в примерах приведите к своему шаблону docker-compose.

Сервер исполнения процессов (bpm)

Подходит для сценариев с «Веб-запросом» к API, где в инструкции провайдера указаны дополнительные корни (пример — GigaChat: сертификаты).

services:
  bpm:
    environment:
      NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/mincifry-ca.pem
    volumes:
      - ./certs/mincifry-ca.pem:/usr/local/share/ca-certificates/mincifry-ca.pem:ro

Шаг: применить изменения

Пересоздайте контейнер bpm, чтобы Node.js прочитал переменную при старте:

docker compose up -d --force-recreate bpm

Сервер Бипиума (bpium)

Используйте, если TLS нужен для исходящих запросов сервера Бипиума (например, SSO по HTTPS к Keycloak на УЦ заказчика).

services:
  bpium:
    environment:
      NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/company-chain.pem
    volumes:
      - ./certs/company-chain.pem:/usr/local/share/ca-certificates/company-chain.pem:ro

Шаг: применить изменения

docker compose up -d --force-recreate bpium

Настройка без Docker

Windows (Bpium.exe, служба)

Шаг 1: Файл PEM

Разместите файл, например: C:\Bpium\certs\company-chain.pem.

Шаг 2: Переменная среды

Для учётной записи, от которой запускается сервер Бипиума, задайте:

NODE_EXTRA_CA_CERTS=C:\Bpium\certs\company-chain.pem

Через «Переменные среды» Windows, настройки службы, NSSM и т.п.

Шаг 3: Перезапуск

Перезапустите Bpium.exe или службу Бипиума.

Проверка вручную в одной сессии PowerShell:

$env:NODE_EXTRA_CA_CERTS = "C:\Bpium\certs\company-chain.pem"
& "C:\Program Files\Bpium\Bpium.exe"

Путь к исполняемому файлу замените на фактический.

Linux (systemd, скрипт)

На Linux сервер Бипиума обычно запускается исполняемым файлом — по смыслу то же, что Bpium.exe под Windows.

Запуск из оболочки (переменная должна быть задана до запуска процесса сервера):

export NODE_EXTRA_CA_CERTS=/opt/bpium/certs/company-chain.pem
/opt/bpium/bpium

Путь /opt/bpium/bpium замените на реальный исполняемый файл сервера Бипиума или bpm на вашей установке.

Пример unit systemd:

[Service]
Environment=NODE_EXTRA_CA_CERTS=/opt/bpium/certs/company-chain.pem
ExecStart=/opt/bpium/bpium

Для bpm на хосте используйте те же принципы: переменная и путь — для процесса сервера исполнения процессов (его исполняемого файла из поставки).

После замены PEM или значения переменной выполните перезапуск соответствующей службы или процесса.

Проверка результата

1. Убедитесь, что в целевом процессе задана переменная NODE_EXTRA_CA_CERTS (например, printenv в контейнере или Linux, переменные среды Windows).

2. Убедитесь, что файл по указанному пути читается тем же пользователем или контейнером.

3. Повторите сценарий (вебзапрос, вход через SSO) и проверьте логи соответствующего сервиса — bpm или сервера Бипиума.

При необходимости дополнительно проверьте TLS до хоста API утилитой openssl s_client или вызовом tls.connect в Node.js — в том же окружении, где крутится bpm или сервер Бипиума (в контейнере или на хосте без Docker).

Частые вопросы

Связанные материалы

• SSO (Single Sign-On) — настройка входа через Keycloak и других провайдеров; при HTTPS на УЦ заказчика используйте вместе с этой статьёй настройку NODE_EXTRA_CA_CERTS на сервере Бипиума.

• Возможные проблемы в ходе установки и работы — смежные темы HTTPS и интеграций.

Кратко

• NODE_EXTRA_CA_CERTS + PEM с полной цепочкой — штатный способ для Node.js без отключения TLS.

• bpm (сервер исполнения процессов) — исходящие HTTPS из сценариев.

• Сервер Бипиума — исходящие HTTPS из приложения, в т.ч. SSO к Keycloak по HTTPS на УЦ заказчика.

• Доверие Keycloak к LDAPS каталога настраивается в Keycloak и не подменяет NODE_EXTRA_CA_CERTS на сервере Бипиума для HTTPS к Keycloak.