Установка#

Введение#

В разделе описывается установка IAM Proxy на виртуальную машину.

Установка IAM Proxy в среду контейнеризации OpenShift описана в разделе IAM Proxy в контейнере.

Установка сервиса состоит из следующих основных этапов:

1. Подготовка окружения.

2. Создание или изменение профиля развертывания.

3. Подготовка и заполнение конфигурационных артефактов.

4. Развертывание job на сервере CI Jenkins.

5. Непосредственно выполнение развертывания.

6. Проверка результатов развертывания.

Подготовка окружения#

Получить сервера на базе ОС RHEL 8 или Alt Linux Sp8. На серверах должны быть настроены и доступны базовые репозитории пакетов для пакетного менеджера (в зависимости от ОС это .yum или .apt).

При необходимости, получить новые проектные области или доступ к существующим областям инструментов DevOps (Git, Jenkins). Обеспечить чтобы на используемых Jenkins агентах был установлен Ansible 2.9+.

Подготовка дистрибутива#

Получите архив, содержащий файлы поставки дистрибутива. Текущая поставка предусматривает несколько файлов:

• owned дистрибутив - архив оригинальных частей дистрибутива AUTH, включая зависимости на KCSE;

• party дистрибутив - архив зависимостей дистрибутива AUTH, включая зависимости на KCSE;

• vendor дистрибутив - архив полного дистрибутива компонента AUTH, включая зависимые модули KCSE.

Перед установкой, получите необходимые дистрибутивы, затем разархивируйте их в локальный каталог. В случае получения и использования party+owned дистрибутивов, их необходимо предварительно «объединить» специальной утилитой, использование которой подробно описано в подразделе «Объединение разделенного дистрибутива».

Описание установщика#

Основные операции по развертыванию выполняются запуском ansible-playbook, содержимое которого находится в дистрибутиве в файле ansible/platformauth-deploy-playbook.yml. Версия дистрибутива сервиса указывается при запуске ansible-playbook через переменную deploy_platformauth_version.

Пример запуска playbook:

ansible-playbook platformauth-deploy-playbook.yml -i inventories/DemoProfile/hosts --extra-vars "deploy_platformauth_version=1.0.1 tmp_clear=True"

Подготовка базовой конфигурации развертывания#

Здесь и далее под профилем подразумевается совокупность элементов конфигурации и окружения, свойственную определенному стенду.

Рекомендуется использовать систему версионного контроля кода для хранения конфигурации развертывания. Если подготовленные файлы конфигурации уже находятся в такой системе, выполните клонирование репозитория на локальную машину для внесения правок, и сделайте копию шаблонного каталога профиля конфигурации под новый стенд. Пример команды клонирования репозитория, которую необходимо выполнить в терминале:

git clone ssh://git@bitbucket.mycompany.ru:7999/Project/CI_platformauth.git

git checkout develop

При отсутствии шаблона конфигурационных файлов в системе версионного контроля, используйте пример из дистрибутива (примеры профилей расположены по пути deploy\ansible\inventories\).

Заполнение конфигурационных файлов#

Создание или изменение профиля развертывания#

Скопируйте профиль DemoProfile из дистрибутива, как шаблонный для нового профиля StendX.

ansible/inventories/DemoProfile -> ansible/inventories/StendX

Внесение изменений в конфигурационные файлы профиля стенда#

Необходимо внести изменения в параметры профиля StendX. В данной документации приводится описание и назначение определенных параметров. Поставляемые YAML-файлы могут содержать дополнительные комментарии к заполняемым параметрам. Например, дополнительные примеры и уточнения.

Заполнение файла ansible/inventories/StendX/hosts#

С примерами профилей развертывания можно ознакомиться в каталоге дистрибутива deploy/ansible/inventories.

Вместо IP\DNS в файле hosts используйте псевдонимы, с заданием для них в отдельных параметрах ansible_host\ipaddr\dns_name. Пример: keycloak_1 ansible_host=10.x.x.147 ipaddr=10.x.x.147 dns_name=node1.platformauth.mycompany.ru

Шаблон DNS-имени для серверов#

Описание DNS-имени по шаблону вызвано удобством при использовании понятных имен, и тем, что иногда сервера DNS ограничивают максимальную длину FQDN. Как правило, ограничение установлено в 63 символа. Также, имя с самого верхнего уровня домена используется как имя узла при организации распределенного cache в кластере Keycloak, длинна имени узла (node-id), также имеет ограничение по длине (обычно в 23 символа).

DNS-имя формируется по шаблону: <node_name>.<component_name>.<product_code>.<stand_code>.<dns_zone> Где значения в <...> описаны ниже:

Пример: node1.rds.cfge-dev3.my.company.ru

Шаблон является необязательным и носит рекомендательный характер.

Заполнение файла ansible/inventories/StendX/group_vars/all/main.yml#

Здесь описываются основные параметры развертываемого сервиса.

Заполнение раздела с описанием параметров ответвлений(junction) в "proxy_jct_list"#

В этой группе параметров необходимо задать описание параметров маршрутизации запросов на защищаемые сервисы, на который/которые будет осуществляться проксирование. Данный раздел - это список с произвольным количеством элементов/объектов, где каждый элемент описывает параметры проксирования на конкретный backend (указываются все backend с front-UI, имеющиеся на стенде).

Пример прохождения запроса по "непрозрачному" ответвлению

Когда transparent=false и junctionPoint=/jct-point, то URL будет меняться следующим образом:
Запрос: Browser (URL https://my.com/jct-point/myindex.html) -> IAM.Proxy -> BackEnd (URL https://my.com/myindex.html)
Ответ: BackEnd (body html:href: https://my.com/mysubpage.html) -> IAM.Proxy -> Browser (body html:href: https://my.com/jct-point/mysubpage.html)

Пример заполненного раздела для нескольких ответвлений:

proxy_jct_list:
  - junctionName: Мое приложение
    description: Расширенное описание проксируемой подсистемы/сервиса
    junctionPoint: /my-app
    indexUrl: /my-app/start-page
    sslCommonName: ".my.server.ru" # шаблон имени в SAN сертификата backend-серверов
    #https: False # default True
    transparent: True
    serverAddresses: [ "node1.my.server.ru:443" , "node2.my.server.ru:8443" ]
    applyJctRequestFilter: "common/rds-set-header-host-to-backend.location.conf"
  - junctionName: ФП SPAS
    description: Расширенное описание функциональной подсиситемы SPAS
    junctionPoint: /spas-dev
    indexUrl: /spas/admin/index
    sslCommonName: "*" # шаблон имени из CN сертификата backend-серверов (default .mycompany.ru)
    #https: False # default True
    #transparent: False # default False
    serverAddresses: [ "127.0.0.1:8443" ]

В параметре applyJctRequestFilter можно задать набор из следующих значений (через запятую):

• common/oidc-unauth-access.location.conf - отключение функциональности по аутентификации\авторизации на ответвлении;

• common/rds-set-header-host-to-backend.location.conf - переопределение заголовка Host в сторону backend с указанием первого сервера из пула балансировки (необходимо использовать при проксировании в сторону OpenShift);

• common/rds-ssl-sni-on.server.conf - разрешаем передачу имени сервера по SNI, fqdn-имя сервера обязательно задается в proxy_ssl_name (необходимо использовать при проксировании в сторону OpenShift при routes с типом passthrough);

Для значений параметров применяются следующие ограничения:

• при использовании DNS-имен в serverAddresses они должны успешно разрешаться в IP на DNS-сервере, который используется на IAM Proxy (иначе конфигурация не будет применена);

• applyJctRequestFilter должен содержать пути к существующим файлам на IAM Proxy;

• при https = true необходимо обеспечить наличие сертификатов ЦС в TrustStore IAM Proxy;

• параметр junctionPoint должен быть уникален и не должен заканчиваться на /;

• в случае наличия у всех запросов на приложение одного базового корневого контекста, рекомендуется использовать transparent = true;

• использовать в applyJctRequestFilter опции common/rds-set-header-host-to-backend.location.conf и\или common/rds-ssl-sni-on.server.conf при проксировании в k8s\OS.

Заполнение файла ansible/inventories/StendX/group_vars/keycloak.yml#

В этом файле задаются параметры настройки KeyCloak, модуль аутентификации:

• keycloak_db_address, keycloak_db_name, keycloak_db_user_name - задать реквизиты подключения к БД KeyCloak (чистая БД, при отсутствии таблиц они автоматически будут созданы). В keycloak_db_address можно указать несколько серверов ( пример 10.x.x.104:5432,10.x.x.105:5432). В keycloak_db_name можно указать дополнительный параметры для jdbc драйвера(пример keycloak?targetServerType=master&prepareThreshold=0).

• keycloak_system_user - логин системного пользователя, под которым будет работать служба keycloak.

• keycloak_force_install - True/False, принудительная полная установка keycloak, с предварительным удалением всех старых каталогов/файлов KeyCloak на целевом сервере (устанавливается в True при проблемах первоначальной установки, а после успешной установки необходимо выставить в False, чтобы при следующем обновлении случайно не потерять файлы размещенные вручную).

• keycloak_alternative_redirect_uri - задаем дополнительные разрешенные redirect_uri (обычно не требуется задавать, если не используются дополнительные dns-имена до прокси), https://* - разрешает redirect на любые хосты (не рекомендуется использовать при развертывании на Пром).

• keycloak_saml_enabled - True/False, опциональный, по умолчанию False, включение endpoint SAML на Keycloak

• keycloak_deploy_custom_modules - установить дополнительные модули на сервер (указывается имя файла из дистрибутива по пути \keycloak\config\deployments-custom).

  Пример ["custom1.jar","custom2.ear"]

• keycloak_undeploy_modules - удалить модули если они есть на сервере (указывается имя файла, может потребоваться при отключении функциональности или для удаления устаревших модулей).

  Пример ["old1.jar","deprecated2.ear"]

• proxy_oidc_client_jwt_signed_cert - сертификат в формате PEM для аутентификации на OIDC-endpoint методом Signed Jwt. Если определен этот параметр, то метод аутентификации на KeyСloak.SE будет выставлен в Signed Jwt (и будет использован сертификат, вместо client_secret). Значение задается текстом из открытой части сертификата прокси\oidc-клиента (текст между ---BEGIN CERTIFICATE--- и ---END CERTIFICATE---, с исключением перевода строк и пробелов). Закрытый ключ сертификата при этом указывается в параметре oidc_client_rsa_private_key ( для подписания запроса от прокси\oidc-клиента).

  Пример значения: "MIIKmDCCCICgAwIBAgITGAAAAAS5RQdwBbAYQAAAAAAABDANBgkqhkiG9w0BAQsF … JB9bF2BQ=="

• wsSyncSpas - опциональный, настройки для синхронизации\получения справочников из функциональной подсистемы Объединенный сервис авторизации (ОСА).

  • url - endpoint по которому опубликован SOAP интерфейс функциональной подсистемы Объединенный сервис авторизации (ОСА).

  • user, password - логин/пароль для доступа к SOAP интерфейсу (параметр, влияющий на безопасность).

  • roleOwnerType - куда сохранять роли полученные из подсистемы Объединенный сервис авторизации (ОСА) (CLIENT, REALM).

  • roleOwnerName - имя существующего клиента для сохранения ролей (используется при roleOwnerType = CLIENT).

    Пример: "PlatformAuth-Proxy"

  • scheduleTrigger - опциональный, задать периодический запуск синхронизации.

    Пример: "0 0 4 ? * *" запускать по расписанию каждый день в 4 утра

• keycloak

  • smtpServer - задать параметры подключения к почтовому серверу по SMTP и пользователя, которые будут использоваться KeyCloak при отсылке уведомлений по email.

  • realms - опциональный, задает список realms для пользователей, создаваемых развертыванием. По умолчанию создается один пользовательский realm - PlatformAuth.

    Пример:

    realms: # опциональный, создание и обновление дополнительных realms
     - "CustomersAuth"
     - "TestRealm"
    

  • userRealmOptions.afterCreateUserSendEmail - задать True/False. True - при создании польз. отправлять уведомление по email и одноразовый временный токен на смену пароля.

  • userRealmOptions.actionTokenGeneratedByAdminLifespan - задать время жизни токена на смену пароля (в часах).

  • userRealmOptions.ssoSessionIdleTimeout - опциональный, время жизни сессии Keycloak по не активности (в минутах).

  • userRealmOptions.displayName , userRealmOptions.displayNameHtml - отображаемое название сервиса на форме входа.

  • soapApi.verifyCN - SOAP API по управлению УЗ требует аутентификации по клиентскому сертификату, в данном параметре указывается список допустимых CN клиентского сертификата (при mTLS) через |, * - отключить проверку.

  • soapApi.rolesFilter - фильтр по скоупу ролей, подпадающих под синхронизацию через API. Можно указать несколько префиксов ролей через запятую. Если в имени есть / то, считается что это роль клиента (пример, фильтр PlatformAuth-Proxy/ подходит под любую роль клиента PlatformAuth-Proxy).

    Пример: platformauth, EFS, PlatformAuth-Proxy/

  • realm_options - опциональный, список пар значений name+value которые будут установлены как опции для realm ( список доступных опций необходимо смотреть в документации компонента KCSE) Пример:

    realm_options:
     - { name: "accessTokenLifespan", value: "{{ 5*60 }}" } # время действия access-token, задается в секундах
     - { name: "ssoSessionMaxLifespan", value: "{{ 10*60*60 }}" } # максимальное время жизни сессии, задается в секундах
    

  • realm_attributes - опциональный, список пар значений name+value которые будут установлены как атрибуты для realm (список доступных служебных атрибутов необходимо смотреть в документации компонента KCSE, возможно указывать свои произвольные атрибуты)

    Пример:

    realm_attributes:
     - { name: "failureFactor", value: "10" } # кол-во неуспешных попыток входа до установки временной блокировки
    

  • infinispan - опциональный, настройки работы infinispan.

    • bind_port - опциональный, порт по которому будет подключение к кластеру infinispan.

    • tcp_send_buf_size - опциональный, размер буфера на отправку.

    • tcp_recv_buf_size - опциональный, размер буфера на получение.

    • thread_pool_keep_alive_time - опциональный, время жизни подключения при отсутствии активности.

    • thread_pool_min_threads - опциональный, минимальный размер пула потоков.

    • thread_pool_max_threads - опциональный, максимальный размер пула подключений.

Заполнение файла ansible/inventories/StendX/group_vars/proxy.yml#

Заполнение параметров IAM Proxy - модуль проксирования:

• proxy_dns_servers - Dns-сервера (через пробел) актуальные для текущего стенда, используемые для определения ip адресов по dns именам, из модулей прокси.

• proxy_autoload_trusted_certificates - выставить необходимость автоматически загружать trusted-сертификаты с HTTPS-серверов backend при развертывании. При False нужно вручную для всех серверов backend размещать их сертификаты в папке ansible/inventories/StendX/files с префиксом trusted_ и расширением crt.pem (сертификаты д.б. в формате PEM).

• proxy_session_idletime - время таймаута сессии прокси по не активности (в секундах) - устанавливаем значение в 30 минут.

• proxy_session_name - опциональный, по умолчанию PLATFORM_SESSION, задает имя сессионной cookie

• proxy_session_check_addr - включаем привязку сессии к IP (True/False, default False).

• proxy_to_backend_access_token - опциональный, True - передавать в backend access_token вместо id_token.

• proxy_mtls_key_file - файл ключа сертификата прокси, для организации mTLS между прокси и проксируемой подсистемой/backend. Не обязательный.

• proxy_mtls_cert_file - файл сертификата прокси, для организации mTLS между прокси и проксируемой подсистемой/backend. Не обязательный.

• proxy_session_secret- Секрет используемый для шифрования сессии nginx (длинна д.б. > 100 символом, и НЕ должно содержать символов '\$

• proxy_jct_ssl_name - по умолчанию при проверке сертификата на проксируемом сервере считаем валидные CN/SAN(из сертификатов backend) c таким доменом/host.

• proxy_session_check_addr: True - опциональный, умолчание False, привязка сессии прокси к клиентскому IP.

• proxy_to_backend_access_token - опциональный, True - передавать в backend access_token вместо id_token.

• proxy_jct_ssl_name - по умолчанию при проверке сертификата на проксируемом сервере считаем валидные CN\SAN(из сертификатов backend) c таким доменом/host.

• proxy_to_syslog_server - удаленное логгирование событий из Nginx.

• proxy_healtcheck_enable - True/False, опциональный, default False, True - включение активного healtcheck до серверов backend (ответвления в которых есть строка /rds-healthcheck в applyJctRequestFilter), будет вызов GET /healtcheck каждые 10 сек., и ожидается в ответе HTTP-код 200/302 для живого узла (статус доступен по url http://127.0.0.1:10080/status-healtcheck/)

• proxy_keepalive_timeout - timeout [header_timeout], опциональный, default 180 170, параметр (timeout) ограничивающий время клиентских keepalive соединений, второй параметр (header_timeout) попадет в заголовок ответа в формате: Keep-Alive: timeout=header_timeout (по умолчанию будет заголовок Keep-Alive: timeout=170)

• proxy_ssl_session_cache - опциональный, default none, настройка использования cache SSL сессий клиентских подключений, в параметре указывается объем памяти выделенный под cache в мегабайтах (в 1 мегабайте может поместиться около 4000 SSL сессий), так же можно указать none(разрешение использования cache на клиенте) или off(запрет использования cache)

• proxy_support_isam_headers - опциональный, default True, True - добавлять в запросы HTTP-заголовки аналогично ISAM/WebSeal (iv-user, iv-groups, iv-remote-address). Функциональность доступна с версии (IAM Proxy) 4.2.2.

Параметры authz_spas указываются если необходимо использовать функциональность авторизации по URL на разрешениях которые предоставляет ОСА:

• authz_spas_url - опциональный, url для вызова API SPAS функциональной подсистемы ОСА.

• authz_spas_secret - опциональный, секрет для вызова API SPAS функциональной подсистемы ОСА.

• authz_spas_ticket_lifetime - опциональный, частота обновления тикета SPAS функциональной подсистемы ОСА, в секундах.

• authz_spas_ticket_failed_lifetime - опциональный, частота получения тикета SPAS функциональной подсистемы ОСА, если ранее попытка была неуспешной, в секундах.

• authz_spas_rights_lifetime - опциональный, частота обновления полномочий из SPAS функциональной подсистемы ОСА, в секундах.

• authz_spas_rights_failed_lifetime - опциональный, частота обновления полномочий из SPAS функциональной подсистемы ОСА, если ранее попытка была неуспешной, в секундах.

• authz_spas_ssl_verify - опциональный, проверять сертификат на endpoint authz_spas_url.

• oidc_discovery_url - опциональный, задание URL метаданных OIDC IDP.

• oidc_logout_uri - опциональный, задание URL на который делать redirect при logout.

• oidc_use_idp_provider - опциональный, вход на Keycloak через заранее указанного внешнего провайдера.

• oidc_scope - опциональный, задание дополнительных скоупов OIDC при аутентификации.

• oidc_ssl_verify - опциональный, проверять сертификат на endpoint OIDC.

• oidc_use_client_cert - опциональный, использовать клиентский сертификат на endpoint OIDC.

• oidc_host_gray - использовать для подключения к OIDC IDP отдельный ip:port, а не тот который в URL из $oidc_discovery_url (может потребоваться при необходимости использовании серых адресов IDP)

• oidc_host_gray - использовать для подключения к OIDC IDP отдельный ip:port, а не тот который в URL из $oidc_discovery_url (может потребоваться при необходимости использовании серых адресов IDP).

• oidc_post_logon_by_token_call_uri - вызвать endpoint на IDP после восстановления по токену сессии на прокси.

• oidc_access_token_expires_leeway_rand - опциональный, за сколько секунд до истечения access-токена обновить токены ( реальное количество секунд будет выбрано случайным образом от этого числа, а ошибка обновления будет проигнорирована если access-токен действителен). Можно указать проценты от времени действия access-токена, например 20% или 0.2.

• oidc_reuse_refresh_count - опциональный, default -1, определяет количество повторных использований одного refresh токена (значение менее 0 снимает ограничение)

Заполнение файла ansible/inventories/StendX/group_vars/syslogng.yml#

Необходимо задать/проверить параметры модуля событий аудита (Syslog-ng)

• syslogng_audit2_options - параметры для отправки событий в Platform V Audit (обычно равно{{ audit2_options }}).

• syslogng_system_user - логин системного пользователя, под которым будут работать процессы syslog-ng (должно быть равно syslog-ng).

• syslogng_acccepted_ip_adresses - список(тип list), c каких ip-адресов разрешено принимать сообщения в Syslog-NG для отправки в ТС Аудит (обычно уже задан, и заполняется автоматически адресами серверов из групп keycloak и proxy, смотрите демо профиль, при этом сам ip-адрес обязательно указывается в переменной ipaddr у каждого сервера данных групп, в файле hosts)

Заполнение файла ansible/inventories/StendX/group_vars/rds_server.yml#

Задать параметры модуля RDS-Server из профиля, для веток указанных ниже, передаются в конфигурацию приложения(конфигурация springboot application) полностью как будет задано в профиле (корневой узел rds не передается), и их состав не ограничен развертыванием:

• rds.logging.*

• rds.configStore.*

• rds.audit.*

• rds.standin.*

• rds.server.*

• rds.configStore.config-store-jdbc-login - логин к БД компонента PACMAN (CFGA) продукта Platform V Configuration ( CFG).

• rds.configStore.config-store-jdbc-url - url для подключения к БД Platform V Configuration компонента PACMAN ( пример jdbc:postgresql://10.x.x.3:5432/config).

• rds.configStore.configStoreCryptoPas - пароль для шифрования в Platform V Configuration компонента PACMAN (параметр, влияющий на безопасность).

• rds.audit.kafka-servers - сервера для подключения к kafka Platform V Audit (пример 10.x.x.48:9092,10.x.x.179:9092) .

• rds.audit.mockMode - true/false, включение режима заглушки Platform V Audit.

• rds.audit.runWithoutAudit - true/false, true - продолжить работу приложения при проблемах подключения к Platform V Audit.

• rds.standin.cloud.client - параметры КМ Standin для получения состояния платформенного Standin в Прикладном Журнале.

• rds.server.port - порт на котором будет поднят сервер по HTTPs.

• rds.server.http.enable - true/false, true - включить работу по HTTP.

• rds.server.http.port - порт на котором будет поднят сервер по HTTP.

• rds.server.ssl.client-auth - none/need, использовать аутентификацию по клиентскому сертификату при обращении к API.

Примечание: Список параметров развертывания указанный выше не исчерпывающий, указаны параметры на которые стоит обратить внимание.

Заполнение конфиденциальных параметров, влияющих на безопасность#

• Параметры задать в ansible/inventories/StendX/group_vars/all/vault_main_decrypted.yml (игнорируется git, и хранится только локально).

  Список приведен для примера, и может быть как расширен, так и уменьшен по необходимости. Все переменные vault_* используются исключительно на уровне yaml-файлов ansible профиля развертывания.

  • vault_ansible_ssh_pass - пароль пользователя которым заходим при развертывании по ssh.

  • vault_keycloak_admin_password - пароль технического администратора (используется только при развертывании).

  • vault_keycloak_db_password - пароль к БД keycloak (параметр, влияющий на безопасность).

  • vault_keycloak_keystore_password - пароль к базе сертификатов/ключей keycloak (файл keycloak-keystore.p12).

  • vault_keycloak_smtpServer_user_password - пароль пользователя под которым отправляются email-уведомления.

  • vault_proxy_session_secret - Секрет используемый для шифрования сессии nginx (длинна д.б. > 100 символом, и НЕ должно содержать символов '\$" ).

    Содержимое параметра - это случайный набор символов, который можно сгенерировать как вручную, так и какими-то утилитами. Необходимо учесть, что сгенерированная последовательность должна состоять из печатных символов ASCII (за исключением символов '\$"), не должна содержать невидимых символов или символов управления(например, символов переноса строк). Одним из возможных вариантов генерации подобной последовательности на Unix-совместимой станции является использование следующей команды в терминале (или консоли bash):
    head /dev/urandom | LC_ALL=C tr -dc "(-[]-~" | head -c 512

  • vault_rds_config_store_jdbc_pas - пароль к БД Platform V Configuration компонента PACMAN.

• Зашифровать файл с помощью ansible-vault, для этого:

  Ниже только рекомендация, но необязательный подход к шифрованию секретов. Допустимо шифровать как файлы целиком, так и переменные по отдельности, используя отдельно утилиту ansible-vault.

  • записать vault-пароль в ansible/inventories/StendX/group_vars/all/vault-password.txt (игнорируется git, и хранится только локально).

  • скопировать файлы из ansible/inventories/StendX/group_vars/all/ на ПК с установленным ansible(linux).

  • выполнить команду из каталога с файлами chmod a+x encrypt_vaults.sh && ./encrypt_vaults.sh.

  • в результате файл vault_main_decrypted.yml будет зашифрован и записан в vault_main_encrypted.yml.

  • скопировать файл vault_main_encrypted.yml в каталог профиля ansible/inventories/StendX/group_vars/all/.

Заполнение файлов-секретов#

Тут используются сертификаты, описание получения которых описано далее в разделе "Выпуск сертификатов"

• Файлы размещаются в каталоге ansible/inventories/StendX/files/. Описание файлов:

  • keycloak-keystore.p12 - база сертификатов/ключей keycloak в которой содержится сертификат для организации HTTPs на keycloak (смотрите ниже описание выпуска сертификатов в ЦС).

  • proxy-server.crt.pem - открытый ключ для организации HTTPs на прокси.

  • proxy-server.key.pem - закрытый ключ для организации HTTPs на прокси.

  • proxy-server.p12 - из этой базы rds-client берет клиентский сертификат для mTLS при подключении по HTTPs к rds-server (обычно там тот же сертификат, что и в proxy-server.*.pem, но в формате PKCS12).

  • syslogng-server.crt.pem - открытый ключ для организации tls+syslog keycloak→syslog-ng.

  • syslogng-server.key.pem - закрытый ключ для организации tls+syslog keycloak→syslog-ng.

  • rds-server-keystore.p12 - база сертификатов/ключей keycloak в которой содержится сертификат для организации HTTPs на rds-server.

  • trusted_ca_*.cer - доверенные центры сертификации в формате DER, которые выдали сертификаты нам и/или смежным серверам (это как минимум корневой и промежуточный ЦС).

  • trusted_ca_*.crt.pem - доверенные центры сертификации в формате PEM, которые выдали сертификаты нам и/или смежным серверам (это как минимум корневой и промежуточный ЦС).

  • trusted_keycloak_*.cer - доверенные центры сертификации в формате DER, для аутентификации на keycloak по клиентскому сертификату (нужен, если keycloak_funcadmin_required_auth_cert: True).

  • client_trusted_chain.crt.pem - доверенные центры сертификации в формате PEM, для аутентификации на proxy по клиентскому сертификату (нужен, если задан proxy_mtls_front_verify_dn_regex).

  • keycloak/* - файлы и подкаталоги из этого каталога будут доставлены до серверов keycloak, в каталог /opt/keycloak/(переменная keycloak_home). Файлы *.j2 будут обработаны как шаблоны, и попадут на сервера без расширения .j2.

  • keycloak/post-deploy/*.sh - файлы из этого каталога будут запущены на серверах keycloak в конце развертывания ( если расширение будет .sh.j2, то предварительно файл будет обработан как шаблон, и .j2 будет отброшено).

  • proxy/* - файлы и подкаталоги из этого каталога будут доставлены до серверов proxy, в каталог /usr/local/openresty/. Файлы *.j2 будут обработаны как шаблоны, и попадут на сервера без расширения j2.

• Для конфиденциальных файлов добавляется расширение .decrypted (эти файлы игнорируется git, и хранятся только локально), они будут позже шифроваться.

• Зашифровать конфиденциальные файлы с помощью ansible-vault, для этого можно использовать такой подход:

  • записать vault-пароль в ansible/inventories/StendX/files/vault-password.txt (игнорируется git, и хранится только локально) (параметр, влияющий на безопасность).

  • скопировать файлы из ansible/inventories/StendX/files/ на ПК с установленным ansible(linux).

  • выполнить команду из каталога с файлами chmod a+x encrypt_vaults.sh && ./encrypt_vaults.sh .

  • в результате файлы file_name.xxxxx.decrypted будут зашифрованы и записаны в file_name.xxxxx.

  • скопировать зашифрованные файлы file_name.xxxxx в каталог профиля ansible/inventories/StendX/files/.

В случае необходимости использования SecMan, ознакомитесь с инструкцией по настройке интеграции с Vault на ВМ или Vault в OSE.

Сохранение профиля в GIT#

После внесения всех изменений, наш каталог с профилем сохраняется в GIT, и размещается под версионный контроль. Сохранение лучше делать в отдельной ветке, соответствующей типу среды или конкретному стенду.

git branch StendX
git checkout StendX
git commit -a -m "init StendX"
git push origin

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

Выпуск сертификатов#

Для работы HTTPS по фронтовым dns-именам потребуются сертификаты, выпущенные Центром Сертификации.

Так же потребуются сертификаты для межмодульного взаимодействия по TLS.

Создайте сертификаты на используемые в сервисах DNS-имена(должны быть в поле SAN сертификата), с использованием доверенных ЦС (ниже указаны рекомендуемые CN):

• platform-stendx.my.company.ru(значение из параметра proxy_dnsname, для пром platform.my.company.ru).

• platformauth-stendx.my.company.ru(значение из параметра keycloak_dnsname, для пром platformauth.my.company.ru).

• platform-syslogng-stendx.my.company.ru(обмен по TLS между Keycloak и Syslog-ng, для пром platform-syslogng.my.company.ru).

• platform-rds-stendx.my.company.ru(значения из параметра rds_server_urls, для пром platform-rds.my.company.ru).

Для каждого сертификата нужно будет ОБЯЗАТЕЛЬНО в альтернативных dns-псевдонимах (Subject Alternative Names) указать все используемые под сервис dns-имена (fqdn всех nodes и под балансировщик при его наличии, например platform-stendx.my.company.ru, node1.platform-stendx.my.company.ru), и желательно(но не обязательно) указать IP всех конечных серверов включая балансировщик (нужно в случе если планируется обращаться к серверам по IP).

Регистрация DNS имен в службе DNS#

Доменные имена прокси и провайдера идентификации platform-stendx.my.company.ru , platformauth-stendx.my.company.ru необходимо зарегистрировать в вашем DNS, указав для них IP-адреса балансировщиков(или IP самого сервера если он один) для прокси и провайдера идентификации(keycloak) соответственно. Для корректного функционирования решения достаточно заведения в DNS записи с типом A или B.

Если имеется несколько серверов у компонента, то для каждого отдельного сервера рекомендуется зарегистрировать во внутреннем DNS отдельное имя, прибавив к основному DNS-имени приставку node1., node2. и т.д. Пример имен двух серверов Keycloak: node1.platformauth-stendx.my.company.ru, node2.platformauth-stendx.my.company.ru

Создание в Jenkins задачи по установке#

При использовании Jenkins для установки, необходимо в нем создать задачу с типом pipeline, которая будет запускать ansible-playbook установщика.

Создание задачи:

1. Найти Jenkins-файл в дистрибутиве: deploy/jenkins/PlatformAuth_CDL.jenkinsfile.

2. Скопировать Jenkins-файл в тот же Git-репозиторий (например в папку jenkins/), где размещаются профили развертывания. В Jenkins-файл правим по желанию значения в defaultValue секции parameters{} под свой стенд, чтобы не вводить их потом каждый раз.

3. Перейти в Jenkins и создать Jenkins job c типом Pipeline\<img height="300px" src="resources/new_item.png" /><img height="300px" src="resources/pipeline.png"/>.

4. В блоке Pipeline, в поле Definition необходимо выбрать Pipeline script from SCS, затем в поле SCM выбрать GIT.

5. В поле Repository URL указываем ссылку на Git-репозиторий из п.2.

6. В поле Credentials указываем учетную запись которая имеет доступ на чтение к Git-репозиторию.

7. Прописываем git-ветку в поле Branch Specifier, в Script Path относительный путь до Jenkins-файла ( например jenkins/PlatformAuth_CDL.jenkinsfile) и нажимаем Сохранить.

8. Нажимаем кнопку Собрать сейчас. Сборка возможно будет с ошибкой, но это нормально. На этом этапе Jenkins job добавит необходимые параметры запуска из Jenkins-файла, и при следующем запуске они появятся в job.

9. После обновления страницы появится кнопка Собрать с параметрами, по которой можно будет запустить сборку с параметрами:

   • STAND- наименование стенда, то есть inventory для ansible (это имя папки в ansible/inventories/, например StendX);

   • PLATFORMAUTH_VERSION- версия артефакта дистрибутива размещенного в Nexus;

   • EMAIL_RECIPIENTS- опциональный параметр, email для уведомлений о результате выполнения job;

   • PLAYBOOK- имя файла с playbook;

   • SSH_USER- опциональный параметр, учетная запись ssh-пользователя для подключения к хостам, ее необходимо указывать только при запуске подготовки серверов, когда необходимы привилегии sudo root;

   • LIMIT- опциональный параметр, задать ansible параметр limit для ограничения установки на выбранные хосты\группы которые расположены файле hosts (например когда мы хотим установить новую версию на часть серверов);

   • STAGE_DEPLOY- включить выполнение запуска указанного playbook;

   • DEBUG- включение подробного уровня логирования в ansible (-vvv);

   • USE_SECMAN- включить использование хранилища секретов Hashicorp Vault;

Дополнительно, для нормальной работы может потребоваться создать credentials в Jenkins с ID:

• VAULT_PASSWD - с типом Secret text, в нем сохраняется секрет, на котором зашифрованы в ansible-vault параметры профиля развертывания (в нем сохраняется содержимое из файла ansible/inventories/StendX/files/vault-password.txt используемого в разделах "Заполнение файлов-секретов" и "Заполнение конфиденциальных параметров, влияющих на безопасность");

• SSH_USER - с типом SSH Username with private key, в нем сохраняется закрытый ssh-ключ, который потом выбирается при запуске подготовки серверов;

• Secman_app_role - с типом Vault App Role Credential, в нем сохраняется информация о роли и секретах хранимых в Hashicorp Vault.

Установка сервиса на сервера стенда#

Выполнение скриптов подготовки серверов#

Все действия, требующие прав суперпользователя (root) вынесены в отдельные shell-скрипты, которые необходимо предварительно выполнить на серверах, предназначенных для развертывания.

Скрипты подготовки, включенные в дистрибутив (список в порядке очередности запуска):

• prep-deployers.sh - выполняется на всех серверах в первую очередь. При запуске скрипта необходимо будет задать пароль для ssh-пользователя (deployer) под которым будет производиться развертывание (значение из переменной профиля vault_ansible_ssh_pass). Так же пароль можно указать при запуске prep-deployers.sh в первом параметре или в переменной окружения deployer_pass (параметр, влияющий на безопасность), если пароль не указан при запуске он будет запрошен в терминале;

• prep-keycloak.sh - выполняется на всех серверах группы keycloak;

• prep-nginx.sh - выполняется на всех серверах группы proxy;

• prep-rds-client.sh - выполняется на всех серверах группы nginx, при использовании конфигурирования через rds-server и компонент PACMAN (CFGA) продукта Platform V Configuration (CFG);

• prep-rds-server.sh - выполняется на всех серверах группы rds_server, при использовании конфигурирования через rds-server и компонент PACMAN (CFGA) продукта Platform V Configuration (CFG);

• prep-syslog-ng.sh - выполняется на всех серверах группы syslogng;

• prep-lb-nginx.sh - выполняется на всех серверах группы proxy;

• prep-vault-agent.sh - выполняется на всех серверах группы loadbalancer;

• unprep-all.sh - удалить все установленные ранее компоненты сервиса, и все преднастройки;

Примечания:

Файл дистрибутива system-prepare.zip содержит все файлы необходимые для подготовки серверов к установке (файлы, скрипты, пакеты необходимые для установки), и для подготовки серверов необходимо использовать его.

При ручной установке важен порядок запуска скриптов.

Описание прав linux-пользователей, которые создаются скриптами подготовки - prep-syslog-ng.sh, prep-rds-server.sh , prep-keycloak.sh, prep-nginx.sh, prep-deployers-dev.sh,prep-deployers.sh,prep-fluent-bit.sh , prep-vault-agent.sh.

Запуск скриптов используя ansible-playbook#

Необходимо подготовить job в Jenkins, как описано выше в разделе "Создание в Jenkins задачи по установке".

При запуске подготовки все параметры указываем так же, как и при основном развертывании, за исключением параметров:

• в PLAYBOOK выбирается значение platformauth-system-prepare-playbook.yml;

• в SSH_USER выбирается Jenkins credential с закрытым ssh-ключем учетной записи для подключения к хостам по ssh, данная учетная запись должна иметь привилегии sudo root на всех серверах на которые будет производиться установка.

Если нет потребности использовать Jenkins, то можно запустить и без него. Пример запуска playbook из командной строки:

cd ansible
ANSIBLE_STDOUT_CALLBACK="debug" && \
ansible-playbook platformauth-deploy-playbook.yml \
  -i inventories/StendX/hosts \
  --vault-password-file ~/vault-password.txt \
  --extra-vars "deploy_platformauth_version=D-01.000.03-1.0.1 tmp_clear=True ansible_user=myusername ansible_password= ansible_ssh_private_key_file=~/.ssh/mykey.pem"

Запуск скриптов вручную#

В случае невозможности использовать ansible для запуска скриптов под привилегированным пользователем, их можно выполнить вручную на каждом сервере из консоли.

Пример установки скриптов:

# На сервера из списка(на все сервера сервиса) скопировать из дистрибутива файл system-prepare.zip и из каталога с этим архивом
# выполнить следующие команды (под пользователем root):
sudo yum -y install unzip
unzip system-prepare.zip -d /tmp && cd /tmp/system-prepare
chmod a+x *.sh
sudo ./prep-deployers.sh

# сервера keycloak:
# На данных серверах выполнить
sudo ./prep-keycloak.sh

# сервера nginx, syslog-ng:
# На данных серверах выполнить
sudo ./prep-nginx.sh
sudo ./prep-rds-client.sh
sudo ./prep-syslog-ng

Запуск развертывания сервиса на стенд#

Необходимо подготовить job в Jenkins, как описано выше в разделе "Создание в Jenkins задачи по установке".

1. Откройте job по установке, и нажимаем "Собрать с параметрами".

2. Заполните параметры сборки:

   • STAND, наименование стенда, то есть inventory для ansible (это имя папки в ansible/inventories/, например StendX);

   • PLATFORMAUTH_VERSION, версия устанавливаемого артефакта дистрибутива компонента AUTH размещенного в Nexus;

   • PLAYBOOK, выбираем playbook platformauth-deploy-playbook.yml;

3. Нажать "Собрать" и ожидать завершения задачи.

4. Если выполнение задачи завершилось успешно, то проверьте работоспособность развернутого стенда.

   Для проверки работоспособности можно пойти на корневую страницу IAM Proxy по ссылке https://<iam_proxy_hostname>:<proxy_https_port>/ ,
   где:

   • iam_proxy_hostname - FQDN IAM Proxy (параметр профиля proxy_dnsname);

   • proxy_https_port - порт, определенный в профиле развертывания (параметр lb_https_port).

   Если все успешно, то должны получить примерно такую страницу:
   

Обратите внимание, что при развертывании IAM Proxy с использованием аутентификации на Identity Provider, необходимо будет пройти аутентификацию и ввести учетные данные на IDP, а потом уже можно будет попасть на корневую страницу.

Развертывание так же возможно из командной строки вручную, пример:

cd ansible
ansible-playbook platformauth-deploy-playbook.yml \
  -i inventories/StendX/hosts \
  --vault-password-file ~/vault-password.txt \
  --extra-vars "deploy_platformauth_version=D-01.000.03-1.0.1 tmp_clear=True"

Загрузка ролевой модели сервиса в Объединенный сервис авторизации (ОСА)#

Для того чтобы назначать пользователю роли (в частности роль функционального администратора сервиса аутентификации) необходимо добавить их в ролевую модель Объединенного сервиса авторизации (ОСА), для этого выполните следующие шаги:

1. Создайте в Объединенном сервисе авторизации (ОСА) модуль с именем platformauth.

2. Импортируйте в модуль ролевую модель из файла (файл из дистрибутива keycloak\config\roleModel_platformauth.xml).

Полный переход на работу через сервис аутентификации платформы#

Работая с платформой с доступом к ресурсам приложений используйте проксирование через сервис аутентификации (компонент IAM Proxy), а в приложениях используйте прямую интеграцию с Open ID Connect провайдером платформы ( компонент KeyCloak.SE).

Объединение разделенного дистрибутива#

В случае получения поставки в виде разделенного дистрибутива, и если потребуется восстановить дистрибутив из разделенного на owned и 3rd-party части, необходимо для объединения использовать job jenkins, идущую в поставке.

Данный job загружает из Nexus\URL две части (owned и 3rd-party), объединяет их, и выгружает объединенный дистрибутив в Nexus\URL.

Файл ее конфигурации находится в дистрибутиве по пути: deploy/tools/import-job-to-jenkins/config_Inject3rdParty_Job.xml

Параметры job#

Описание работы job#

1. По переданному URL (OWNED_PART_DOWNLOAD_URL), в коде job за счет замены подстроки owned-distrib.zip на party-distrib.zip и на owned.pom, произойдет скачивание owned-части, party-части и pom-файлов.

2. Запустится процесс слияния owned-части и party-части дистрибутива средствами утилиты inject3rdParty. Далее запустится процесс дополнительного слияния owned-части и party-части дистрибутива с помощью отдельного sh-скрипта.

3. Выполнится выгрузка восстановленного дистрибутива по указанным параметрам в Nexus.

Соответствие имен параметров для разных сред и инструментов установки#

Для определения параметров в дистрибутиве присутствуют файлы примеров настроек, которые требуется заполнить необходимыми значениями под конкретный стенд, с учетом требований к системе и используемой инфраструктуры. Файлы примера настроек для установки IAM Proxy на VM(профиль для ansible) располагаются в файлах bin-дистрибутива в папке package/deploy/ansible/inventories/DemoProfile/group_vars.

Файлы примера настроек для установки IAM Proxy в OpenShift (с использованием утилит Platform V DevOps Tools CDJE) располагаются в файле cfg-дистрибутива в папке package/conf/config/parameters.

Описание и соответствие параметров настройки приведены в таблице ниже.

Примечания#

Параметры влияющие на безопасность отмечены по тексту примечанием - (параметр, влияющий на безопасность).