Обновление SSL-сертификата для HTTPS-доступа к ПУИД

Содержание

Обновление SSL-сертификата для HTTPS-доступа к ПУИД#

Данный раздел описывает порядок замены SSL-сертификата, который HAProxy использует для HTTPS-доступа к компонентам UIDM, и действия по добавлению сертификата или его корневых сертификатов в доверенные хранилища.

Общая схема#

Входящий HTTPS-трафик к ПУИД терминирует HAProxy. HAProxy принимает HTTPS-соединение от браузеров, серверов интегрируемых приложений и других клиентов, а затем передает запросы к компонентам UIDM по внутренним HTTP-маршрутам.

Основной файл настройки HAProxy на сервере UIDM в установленной системе:

/etc/haproxy/haproxy_roox.cfg

HAProxy использует стандартный файл /etc/haproxy/haproxy.cfg; в поставке UIDM этот файл является ссылкой на /etc/haproxy/haproxy_roox.cfg.

Сертификат для входящего HTTPS-соединения указан в директиве bind секции frontend main. Используется PEM bundle:

haproxy
bind *:443 ssl no-sslv3 crt /etc/ssl/certs/server.bundle.pem

server.bundle.pem должен содержать в одном PEM-файле сертификат сервера, при необходимости промежуточные сертификаты УЦ и закрытый ключ сервера. Подробный синтаксис параметра crt описан в официальной документации HAProxy:.

Если используется самоподписанный сертификат или сертификат, подписанный корпоративным УЦ, администратор должен добавить доверенный сертификат в две группы систем:

Серверы UIDM, на которых работают Java-приложения.
Серверы интегрируемых приложений, которые вызывают HTTPS endpoints UIDM.

Если сертификат подписан публичным УЦ, который уже входит в системные и Java-хранилища доверенных сертификатов, добавление в доверенные хранилища не требуется. Проверку следует выполнять с конкретного сервера-клиента.

Типовые операции администратора#

Подготовка новый сертификат для HAProxy#

Для подготовки новый сертификат для HAProxy необходимо:

Получить новый серверный сертификат для публичного FQDN UIDM.
Удостовериться, что в сертификате заполнены актуальные DNS-имена в расширении Subject Alternative Name.
Подготовить PEM bundle в порядке: a. Сертификат сервера. b. Промежуточные сертификаты УЦ, если они есть. c. Закрытый ключ сервера.
Передать файл PEM bundle на сервер HAProxy.

Пример состава файла:

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

sudo sh -c 'cat /etc/ssl/certs/server.crt /etc/ssl/private/server.key > /etc/ssl/certs/server.bundle.pem'
sudo chown root:root /etc/ssl/certs/server.bundle.pem
sudo chmod 0600 /etc/ssl/certs/server.bundle.pem

Примечание

Не следует размещать в файле server.bundle.pem корневой сертификат УЦ, если этого не требует корпоративный регламент. Корневой сертификат обычно распространяется в доверенные хранилища клиентов, а не отправляется сервером в TLS-handshake.

Не следует использовать в промышленной среде сертификат, в котором FQDN UIDM указан только в CN: современные TLS-клиенты проверяют имя сервера по расширению Subject Alternative Name.

Замена сертификат HAProxy#

Для замены сертификата HAProxy необходимо:

Сохранить резервную копию текущего PEM bundle командой:

sudo cp -p /etc/ssl/certs/server.bundle.pem /etc/ssl/certs/server.bundle.pem.$(date +%Y%m%d%H%M%S).bak

Скопировать новый PEM bundle на место рабочего файла:

sudo install -o root -g root -m 0600 /tmp/server.bundle.pem /etc/ssl/certs/server.bundle.pem

Провеить конфигурацию HAProxy командой:
```
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
```
Перезагрузить HAProxy без изменения конфигурации UIDM:
```
sudo systemctl reload haproxy
```
Если reload недоступен в установленной версии или завершился ошибкой, перезапустить HAProxy в согласованное окно работ:
```
sudo systemctl restart haproxy
```

Добавление самоподписанный или корпоративный сертификат в доверенные на серверах UIDM#

Эта операция необходима, если сертификат HAProxy не доверен стандартному Java-хранилищу на серверах UIDM.

Дла добавления самоподписанного или корпоративного сертификата в доверенные на серверах UIDM необходимо:

Определить, какой сертификат необходимо доверять:
- для самоподписанного серверного сертификата — сам серверный сертификат;
- для сертификата, подписанного корпоративным УЦ, — корневой сертификат корпоративного УЦ и, при необходимости, промежуточные сертификаты.
Скопировать доверенный сертификат на каждый сервер UIDM, где работают Java-приложения.
Добавить сертификат в стандартный Java truststore.
Перезапустить Java-сервисы UIDM, для которых изменилось хранилище доверенных сертификатов.
Проверить журнал каждого перезапущенного сервиса.

Java обычно использует стандартное хранилище сертификатов установленного JRE. Как правило стандартный truststore находится по пути:

<JAVA_HOME>/lib/security/cacerts

Примечание

Фактический путь зависит от установленной Java и настроек сервиса. Перед изменением стандартного хранилища следует согласовать действие с администратором платформы: обновление JRE или системного пакета может заменить стандартный файл.

Пароль стандартного cacerts часто равен changeit, но в эксплуатационной среде следует использовать фактический пароль, принятый администратором платформы. Для повторного импорта рекомендуется использовать один и тот же alias: перед импортом проверить наличие старой записи и при необходимости удалите ее.

Пример добавления сертификата в стандартный cacerts:

sudo keytool -importcert \
  -alias uidm-https-ca \
  -file /tmp/uidm-ca.pem \
  -keystore <JAVA_HOME>/lib/security/cacerts \
  -storepass '<password>' \
  -noprompt

Добавление сертификата в доверенные на серверах интегрируемых приложений#

Эта операция необходима для всех систем, которые вызывают UIDM по HTTPS и не доверяют новому сертификату.

Для добавления сертификата в доверенные на серверах интегрируемых приложений необходимо:

Определить технологию клиента: Java, системные утилиты ОС, веб-сервер, application server или другое ПО.
Добавить самоподписанный сертификат или корневой сертификат корпоративного УЦ в доверенное хранилище согласно документации к интегрируемому приложению.
Перезапустить приложение или сервис, который держит truststore в памяти.
Выполнить проверочный HTTPS-запрос к UIDM с сервера интегрируемого приложения.

Для Java-приложений следует использовать truststore-приложения или стандартный механизм JVM. Для системных клиентов Linux рекомендуется доверенное хранилище ОС, согласно документации используемого дистрибутива. Конкретные команды зависят от платформы интегрируемого приложения и должны выполняться по эксплуатационной документации этой платформы.

Откат сертификата HAProxy#

Для отката сертификата HAProxy необходимо:

Вернуть предыдущий PEM bundle из резервной копии командой:
```
sudo cp -p /etc/ssl/certs/server.bundle.pem.<timestamp>.bak /etc/ssl/certs/server.bundle.pem
```
Проверить конфигурацию HAProxy:
```
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
```
Перезагрузить HAProxy командой:
```
sudo systemctl reload haproxy
```
Проверить HTTPS-доступ к UIDM.

Если после замены сертификата новый корпоративный УЦ уже был распространен в доверенные хранилища, удалять его при откате обычно не требуется. Удалять сертификат из доверенных следует только по регламенту управления доверенными УЦ.

Справочник путей и файлов#

Путь на VM	Назначение	Ответственный компонент	Действие после изменения
`/etc/haproxy/haproxy_roox.cfg`	Конфигурация маршрутизации UIDM и SSL offload для HAProxy. Файл `/etc/haproxy/haproxy.cfg` является ссылкой на этот файл	HAProxy	Выполнить проверку конфигурации и reload/restart HAProxy
`/etc/ssl/certs/server.bundle.pem`	PEM bundle с закрытым ключом и сертификатом, который HAProxy предъявляет HTTPS-клиентам UIDM	HAProxy	Выполнить проверку конфигурации и reload/restart HAProxy
`/var/log/haproxy.log`	Журнал HAProxy	HAProxy	Использовать для проверки reload/restart и ошибок TLS
`<JAVA_HOME>/lib/security/cacerts`	Стандартное Java-хранилище доверенных сертификатов. Обычно находится по этому пути, но фактический путь зависит от установленной Java и настроек сервиса	Соответствующий Java-сервис UIDM или интегрируемое Java-приложение	Перезапустить сервис или приложение

Проверка после изменения#

Проверка HAProxy#

Для проверки работы HAProxy необходимо:

Проверить конфигурацию командой:
```
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
```
Проверить статус сервиса:
```
sudo systemctl status haproxy
```
Проверить журнал:
```
/var/log/haproxy.log
```
Проверить сертификат, который HAProxy отдает клиенту:
```
openssl s_client -connect <uidm-fqdn>:443 -servername <uidm-fqdn> -showcerts
```

В выводе должны отображаться новый сертификат, актуальный срок действия и корректная цепочка сертификатов.

Проверка UIDM#

Для проверки работы UIDM необходимо:

Открыть UI UIDM в браузере по HTTPS и убедитесь, что браузер доверяет сертификату.
Выполнить вход от лица тестового пользователя.
Проверить доступность основных endpoints через HAProxy, например /sso/isAlive.jsp или другой согласованный URL проверки.
Проверить прикладные сценарии и журналы сервисов UIDM.

Журналы основных Java-сервисов UIDM находятся в каталогах вида:

/var/log/<service>/<service>.log

Например:

/var/log/roox-sso/roox-sso.log
/var/log/roox-sso/roox-sso.jsonl
/var/log/roox-api-gateway-wtl/roox-api-gateway-wtl.log
/var/log/roox-api-gateway-wtl/roox-api-gateway-wtl.jsonl

Проверка интегрируемых приложений#

Для проверки работы интегрируемых приложений необходимо:

С сервера интегрируемого приложения выполнить HTTPS-запрос к UIDM тем же FQDN, который использует приложение.
Проверить, что TLS-handshake завершается без ошибок доверия к сертификату.
Выполнить прикладной сценарий интеграции: авторизацию, получение токена, introspection, userinfo или другой endpoint, который использует приложение.
Проверить журнал интегрируемого приложения на отсутствие ошибок вида PKIX path building failed, unable to find valid certification path, certificate verify failed или аналогичных сообщений.

Версии