Keycloak

Это руководство описывает настройку сервиса аутентификации Геном на использование внешнего провайдера Keycloak. Инструкция подготовлена на примере Keycloak версии 20.0.2.

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

Для настройки Геном необходимы привилегии суперпользователя.

Для изменения настроек подсистемы мониторинга следуйте инструкции, соответствующей конфигурации развёртывания ядра мониторинга:

Для изменения значений секретов следуйте инструкции Управление секретами.

Обозначения

В этой инструкции приняты следующие обозначения:

<genome> — IP-адрес или доменное имя узла управления платформой;
<grafana> — IP-адрес или доменное имя узла, на котором развёрнута Grafana;
<monitoring> — IP-адрес или доменное имя узла управления подсистемой мониторинга.

Создание пространства

Если в Keycloak не существует пространство (REALM) для Геном, создайте его:

На панели навигации разверните выпадающий список пространств.
На панели со списком пространств нажмите кнопку Create realm.
В поле Realm name введите название пространства.
Убедитесь, что переключатель Enabled находится в положении On.
Нажмите кнопку Create.

Создание клиента

В Keycloak выполните следующие действия:

На панели навигации разверните выпадающий список пространств и выберите нужное.
На панели навигации выберите Manage Clients.
Нажмите кнопку Create client.
На этапе General Settings заполните форму следующим образом:
- Client type: OpenID Connect.
- Client ID: идентификатор клиента.
Значения прочих полей заполните произвольно.
Нажмите кнопку Next.
На этапе Capability config заполните форму следующим образом:
- Client authentication: On.
- Authorization: Off.
- Standard Flow: включен.
- Direct Access Grants: включен.
- Implicit Flow: выключен.
Нажмите кнопку Save. Будет открыта страница со сведениями о клиенте.
Во вкладке Settings измените значения следующих параметров:
- Root URL: укажите URL узла управления платформой:
  https://<genome>/
- Home URL: укажите URL узла управления платформой:
  https://<genome>/
- Valid Redirect URIs: список адресов, на которые Keycloak может перенаправить пользователя при успешной аутентификации.
  Укажите URL Геном, Grafana и узла управления подсистемой мониторинга:
  
  https://<genome>/after-auth https://<monitoring>/vision/api/v1/auth/login https://<grafana>/vision/api/v1/auth/login-grafana
  
  При доступности приложений по доменному имени и IP-адресу укажите все возможные варианты, например:
  
  https://genome.example.com/after-auth https://192.168.0.1/after-auth https://monitoring.example.com/vision/api/v1/auth/login https://192.168.0.2/vision/api/v1/auth/login https://grafana.example.com/vision/api/v1/auth/login-grafana https://192.168.0.3/vision/api/v1/auth/login-grafana
- Valid post logout redirect URIs:
  https://<genome>/after-logout
- Web Origins: заполните так же, как и Valid redirect URIs.
- Admin URL: укажите URL узла управления платформой.
  https://<genome>/
Нажмите кнопку Save.

Создание ролей

В Keycloak создайте роли, перечисленные в таблице:

Таблица 1. Роли
Role name	Description
`bmc_access`	Пользователь BMC
`inventory`	Администратор инвентаря
`obj_model`	Администратор объектной модели
`role_model`	Администратор информационной безопасности
`ssh_access_no_sudo`	Пользователь SSH без sudo
`ssh_access_sudo`	Пользователь SSH с sudo
`vsn_config`	Администратор объектов мониторинга

На панели навигации выберите Manage Clients.
В колонке Client ID нажмите на ссылку с идентификатором нужного клиента.
Выберите вкладку Roles.
Нажмите кнопку Create role.
Заполните форму в соответствии с таблицей Роли.
Нажмите кнопку Save.
С помощью строки навигации в верхней части страницы вернитесь во вкладку Roles.

Создание и назначение пользовательских ролей

Подсистема мониторинга позволяет создавать роли, дающие доступ только к определённым ресурсам. Такие роли называются пользовательскими. Для их корректной работы нужно выполнить настройки и на стороне подсистемы мониторинга, и на стороне Keycloak.

Создание роли в подсистеме мониторинга

Чтобы создать пользовательскую роль:

Авторизуйтесь в подсистеме мониторинга.
На панели навигации выберите Безопасность Ролевая модель.
Нажмите кнопку Добавить роль.
Укажите название роли и нажмите кнопку Сохранить. В таблице появится новая колонка с названием созданной роли.
Поставьте флаги на пересечении колонки нужной роли со строками привилегий и нажмите кнопку Сохранить.

Создание роли в Keycloak

Чтобы создать пользовательскую роль в Keycloak:

На панели навигации выберите Manage Clients.
В колонке Client ID нажмите на ссылку с идентификатором нужного клиента.
Выберите вкладку Roles.
Нажмите кнопку Create role.
В поле Role name укажите то же название роли, что и в подсистеме мониторинга.
Нажмите кнопку Save.

Назначение роли пользователям и группам

Чтобы назначить роль пользователям Keycloak:

На панели навигации выберите Manage Users.
В колонке Username нажмите на ссылку с названием учётной записи нужного пользователя.
Выберите вкладку Role mapping.
Нажмите кнопку Assign role.
Раскройте выпадающий список Filter by realm roles и выберите Filter by clients.
Выберите нужные роли и нажмите кнопку Assign.

Чтобы назначить роль группе пользователей Keycloak:

На панели навигации выберите Manage Groups.
В колонке Group name нажмите на ссылку с названием нужной роли.
Выберите вкладку Role mapping.
Нажмите кнопку Assign role.
Раскройте выпадающий список Filter by realm roles и выберите Filter by clients.
Выберите нужные роли и нажмите кнопку Assign.

Настройка платформы

Настройте аутентификацию на стороне платформы:

Подключитесь к узлу управления платформой.
Внесите изменения в конфигурационный файл /opt/skala-r/platform-services/configs/auth-service.yml.
- iam.auth_server: URL сервера Keycloak, например, https://keycloak.example.com/.
- iam.client_id: идентификатор клиента.
- iam.client_secret: секрет клиента.
  Значение этого поля указывайте в открытом виде, без использования защищённого хранилища Ansible Vault.
  
  Чтобы получить значение секрета, выполните в Keycloak следующие действия:
  
  На панели навигации выберите Manage Clients.
  
  В колонке Client ID нажмите на ссылку с идентификатором нужного клиента.
  
  Выберите вкладку Credentials.
  
  Скопируйте значение поля Client secret.
- iam.provider: keycloak.
- iam.realm: название пространства (REALM).
- iam.request_timeout: ограничение по времени на запрос к Keycloak.
- iam.tls_insecure_skip_verify: пропуск проверки TLS-сертификатов.
- iam.token_introspection.enabled: состояние интроспекции (true — включена, false — выключена).
- iam.token_introspection.interval: длительность интервала дополнительной интроспекции.
- sync.admin_server: URL сервера Keycloak.
- sync.fetch_interval: периодичность выполнения синхронизации.
- sync.tech_auth_client_id: идентификатор клиента, используемый для авторизации сервиса.
- sync.tech_auth_client_secret: секрет клиента, применяемый для получения токена доступа.
- sync.tech_auth_password: пароль учётной записи.
- sync.tech_auth_username: название учётной записи, от имени которой выполняется синхронизация данных.

Значения ключей iam.request_timeout и iam.token_introspection.interval указывайте в виде строки, состоящей из числа и следующего за ним обозначения единицы времени. Например, 30s обозначает 30 секунд, а 2m — 2 минуты.

Пример настройки

---
# ...
iam:
  provider: keycloak
  auth_server: "https://keycloak.example.com/"
  realm: "genome"
  client_id: "genome"
  client_secret: "********"
  tls_insecure_skip_verify: true
  request_timeout: 5s
  token_introspection:
    enabled: true
    interval: 10m
# ...
sync:
  admin_server: "https://keycloak.example.com"
  tech_auth_client_id: "admin"
  tech_auth_client_secret: "********"
  tech_auth_username: "genome-tech-user"
  tech_auth_password: "password"
  fetch_interval: 1h
# ...

Настройка подсистемы мониторинга

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

auth.admin_server: URL сервера Keycloak, например, https://keycloak.example.com/.
auth.auth_server: URL сервера Keycloak, например, https://keycloak.example.com/.
auth.auth_type: keycloak.
auth.client_id: идентификатор приложения на стороне Keycloak.
auth.enabled: true.
auth.tls_insecure_skip_verify: пропуск проверки TLS-сертификата.

Не изменяйте значение параметра auth.client_secret! Вместо этого измените значение секрета vault.auth.client_secret!

Пример настройки

---
# ...
auth:
  enabled: true
  auth_type: keycloak
  auth_server: "https://keycloak.example.com/"
  admin_server: "https://keycloak.example.com"
  client_id: "genome"
  client_secret: vault.auth.client_secret
  tls_insecure_skip_verify: true
# ...

Настройка автоматической рассылки уведомлений

Рекомендуется настроить отдельное техническое приложение (клиент), которое будет использоваться для подключения к Keycloak и получения списков пользователей и ролей.

Создание технического пользователя

Создайте пользователя Keycloak, от имени которого будет выполняться рассылка уведомлений:

На панели навигации разверните выпадающий список пространств и выберите пространство master.
На панели навигации выберите Manage Users.
Нажмите кнопку Add user. Будет открыта форма Create user.
В поле Username укажите значение genome-tech-user.
Нажмите кнопку Save. Будет открыта страница с данными пользователя.
Выберите вкладку Credentials.
Нажмите кнопку Set password.
Заполните форму:
- В полях Password и Password confirmation введите пароль технического пользователя и его подтверждение.
- Переведите переключатель Temporary в положение Off.
Нажмите кнопку Save.
Подтвердите установку пароля.
Выберите вкладку Role mapping.
Нажмите кнопку Assign role.
Раскройте выпадающий список Filter by realm roles и выберите Filter by clients.
Для пространства Геном выберите следующие роли:
- view-clients;
- view-users;
- view-realm.
Нажмите кнопку Assign.

Настройка подсистемы мониторинга

В настройках подсистемы мониторинга измените значения указанных параметров:

iamsyncer.fetch_interval;
iamsyncer.tech_auth_client_id;
iamsyncer.tech_auth_username;
iamsyncer.user_update_enabled.

Пример заполнения

---
# ...
iamsyncer:
  tls_insecure_skip_verify: true
  request_timeout: 5
  systemd_service: vision_iamsyncer.service
  user_update_enabled: true
  tech_auth_client_id: "genome"
  tech_auth_username: "genome-tech-user"
  tech_auth_password: vault.auth.tech_auth_password
  fetch_interval: 3600
# ...

В хранилище секретов в значении параметра vault.auth.tech_auth_password укажите пароль технического пользователя.

Если подсистема мониторинга развёрнута на одном узле, примените изменения в конфигурации сервиса vision_iamsyncer одним из способов:

Вручную перезапустите службу vision_iamsyncer:
```
systemctl restart vision_iamsyncer
```

Запустите скрипт /opt/skala-r/vision/tools/update_server_configs.sh.

Этот способ рекомендуется в тех случаях, когда менялись ещё какие-либо фрагменты конфигурации для других компонентов.

Для проверки работы сервиса vision_iamsyncer выполните команду:
```
tail -f /opt/skala-r/var/log/vision/server/vision_iamsyncer/vision_iamsyncer.log
```

Допускается использование клиента подсистемы мониторинга в качестве технического клиента для запроса данных пользователей и ролей. В этом случае необходимо сконфигурировать его в соответствии с описанием, приведённым для технического приложения в данном разделе.

Поведение Keycloak при интеграции с Active Directory

Keycloak поддерживает интеграцию с Active Directory (далее — AD). Ниже перечислены особенности, которые необходимо учитывать при работе Keycloak с AD.

При блокировке пользователя в AD он не сможет войти в Геном. Будет возникать ошибка с указанием на неверные логин или пароль.
При изменении списка групп пользователя в AD данные в Keycloak обновятся при плановой синхронизации данных.
При исключении пользователя из всех групп, связанных с ролями Геном, отключение пользователя произойдёт после синхронизации Keycloak с AD при новой попытке входа в систему. Если в момент синхронизации была активная сессия, пользователь сможет пользоваться Геном до истечения срока жизни токена.
Время отключения пользователя можно регулировать:
- Через включение параметра Periodic changed users sync и указания Changed users sync period в Keycloak в Configure User federation LDAP provider Synchronization settings. Чем меньше значение, тем чаще будут синхронизироваться пользователи между AD и Keycloak.
- Через изменение в Keycloak параметра Configure Realm settings Tokens Access token Access Token Lifespan, который управляет, как часто будут обновляться токен пользователя и его полномочия в виде ролей.

При активной сессии отключение пользователя будет произведено в следующих случаях:

при завершении сессии в административном интерфейсе Keycloak;
по истечении срока жизни активного токена;
при принудительной синхронизации Keycloak с AD.

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