Настройка Keycloak

Закрома.Диск использует Keycloak для входа пользователей в Web UI и WebDAV. Keycloak можно установить из поставки Закрома.Диск или подключить уже существующий сервис.

Подготовить Keycloak можно двумя способами:

• импортировать подготовленный realm из файла files/realm.json;
• настроить realm вручную по шагам ниже.

realm в этой инструкции - это область пользователей Keycloak, client - приложение Закрома.Диск в Keycloak, service account - служебная учетная запись приложения, а mapper - правило сопоставления данных из Keycloak или AD/LDAP.

Подготовка Keycloak

1. Заполнение переменных Keycloak

Отредактируйте файл inventories/<inventory>/group_vars/keycloak.yml.

Copy
1---
2postgres_host: "postgresql.zakroma.internal"
3base_domain: "zakroma.internal"
4
5keycloak_quarkus_jdbc_url: "jdbc:postgresql://{{ postgres_host }}:5432/keycloak"
6keycloak_quarkus_db_schema: "keycloak"
7keycloak_quarkus_db_user: "keycloak_user"
8keycloak_quarkus_db_pass: "<KEYCLOAK_DB_PASSWORD>"
9
10keycloak_quarkus_bootstrap_admin_user: "admin"
11keycloak_quarkus_bootstrap_admin_password: "<KEYCLOAK_ADMIN_PASSWORD>"
12
13keycloak_quarkus_ha_enabled: false
14keycloak_quarkus_hostname: "https://keycloak.{{ base_domain }}:{{ keycloak_quarkus_https_port }}"
15keycloak_quarkus_hostname_admin: "https://keycloak.{{ base_domain }}:{{ keycloak_quarkus_https_port }}"
16
17keycloak_quarkus_https_key_file_enabled: true
18keycloak_quarkus_service_user: "keycloak"
19keycloak_quarkus_service_group: "keycloak"
20tls_crt_dir: "/opt/keycloak"
21keycloak_quarkus_dest: "/opt/keycloak"
22keycloak_quarkus_cert_file: "{{ tls_crt_dir }}/keycloak.crt"
23keycloak_quarkus_key_file: "{{ tls_crt_dir }}/keycloak.key"
24
25keycloak_quarkus_version: "26.3.2"
26keycloak_quarkus_http_port: 8180
27keycloak_quarkus_https_port: 8443
28keycloak_quarkus_proxy_mode: "none"
29keycloak_quarkus_service_restart_always: true
30keycloak_quarkus_java_heap_opts: "-Xms1024m -Xmx2048m"
31keycloak_quarkus_http_enabled: true

2. Установка Keycloak

Запустите playbook из корня распакованного архива поставки:

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook -i inventories/<inventory>/hosts playbooks/sample-play-keycloak.yml

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

Copy
1https://keycloak.zakroma.internal:8443

3. Выбор способа подготовки realm

Если вам подходит базовая конфигурация из поставки, используйте подготовленный realm из файла files/realm.json и импортируйте его playbook’ом.

Если настройки пользователей, ролей, групп или внешнего каталога отличаются от примера, настройте realm вручную. Ручная настройка описана в следующих шагах и подходит для production-контуров, где параметры Keycloak согласуются с существующими правилами доступа.

4. Импорт подготовленного realm

Запустите playbook импорта:

Copy
1ANSIBLE_CONFIG=ansible.cfg ansible-playbook -i inventories/<inventory>/hosts playbooks/sample-play-keycloak-copy-realm.yml

После импорта проверьте в административном интерфейсе Keycloak, что появилась область пользователей zakroma и приложение zakroma.

Если вы импортировали готовый realm, всё равно проверьте значения Client secret, kid и публичного ключа: они потребуются в переменных Закрома.Диск.

5. Ручная настройка realm

Если готовый файл files/realm.json не используется, создайте настройки вручную.

1. Войдите в административный интерфейс Keycloak.
2. Создайте область пользователей с названием zakroma.
3. Откройте Clients и нажмите Create client.
4. Создайте приложение Закрома.Диск с Client ID: zakroma.
5. В настройках приложения включите:
   • Client authentication: On
   • Authorization: On
   • Direct Access Grants: On или Direct access grants: Enabled

Direct Access Grants нужен для WebDAV-клиентов: WebDAV не проходит интерактивный вход через браузер, поэтому получает токен напрямую. Web UI Закрома.Диск тоже может использовать такой способ входа, если он выбран для вашего контура.

6. Выдача минимальных прав для Закрома.Диск

Закрома.Диск не нужна роль admin. Достаточно прав на чтение области пользователей, пользователей, приложений и групп.

1. Откройте Realm roles.
2. Создайте роль zakroma-realm-role.
3. Откройте Realm roles -> zakroma-realm-role -> Attributes -> Action -> Add associated roles.
4. Выберите фильтр Filter by clients.
5. Добавьте роли:
   • realm-management: view-realm
   • realm-management: view-users
   • realm-management: view-clients
   • realm-management: query-groups
   • realm-management: query-realms
   • realm-management: query-users
   • realm-management: query-clients
   • account: view-groups
6. Откройте Clients -> zakroma -> Service Account Roles.
7. Нажмите Assign role.
8. Выберите zakroma-realm-role и нажмите Assign.

7. Передача имени пользователя в токене

Закрома.Диск должен получать имя пользователя в токене Keycloak.

1. Откройте Clients -> zakroma -> Client scopes -> zakroma-dedicated.
2. Нажмите Add mapper -> By configuration -> User Attribute.
3. Укажите параметры:
   • Mapper Type: User Attribute
   • Name: username-mapper
   • User Attribute: username
   • Token Claim Name: username
   • Claim JSON Type: String
   • Add to access token: On

8. Сохранение значений для Закрома.Диск

1. Откройте Realm Settings -> Keys.
2. Найдите активный ключ с алгоритмом RS256.
3. Скопируйте kid и публичный ключ.
4. Откройте Clients -> zakroma -> Credentials.
5. Скопируйте Client secret.
6. Откройте Realm Settings -> Tokens и задайте:
   • Access Token Lifespan: 10 minutes

Эти значения потребуются в inventories/<inventory>/group_vars/zakroma-disk.yml.

Настройка пользователей

9. Выбор способа работы с пользователями

Закрома.Диск и Keycloak могут работать с пользователями четырьмя способами:

Используйте один основной способ отбора пользователей: либо роль в user_role, либо список групп в user_groups.

10. Настройка внутренних пользователей с ролью

Этот вариант подходит для тестового стенда. Пользователи создаются прямо в Keycloak, а доступ к Закрома.Диск дает роль clouduser.

1. Откройте Clients -> zakroma -> Roles.
2. Создайте роль clouduser.
3. Откройте Users -> Add user.
4. Создайте пользователя, например zakromaadmin.
5. Откройте Users -> zakromaadmin -> Credentials -> Set password.
6. Установите пароль и выключите Temporary.
7. Откройте Users -> zakromaadmin -> Role mapping -> Assign role.
8. Выберите фильтр Filter by clients.
9. Найдите приложение zakroma и назначьте роль clouduser.

В inventories/<inventory>/group_vars/zakroma-disk.yml задайте:

Copy
1zakroma_disk_dsdrive:
2  users_sync:
3    # Синхронизировать пользователей с ролью clouduser.
4    user_role: "clouduser"
5    # Для режима по роли группы не используются.
6    user_groups: ""
7    period: "60s"

11. Настройка внутренних пользователей с группой

Этот вариант подходит, если пользователей создают в Keycloak, а доступ удобнее выдавать через группу.

1. Откройте Groups.
2. Создайте группу, например zakroma-users-group.
3. Откройте нужного пользователя.
4. Добавьте пользователя в группу zakroma-users-group.

В inventories/<inventory>/group_vars/zakroma-disk.yml задайте:

Copy
1zakroma_disk_dsdrive:
2  users_sync:
3    # Для режима по группам роль не используется.
4    user_role: ""
5    # Группа Keycloak, пользователи которой получат доступ к Закрома.Диск.
6    user_groups: "zakroma-users-group"
7    period: "60s"

12. Подключение ролей из AD/LDAP

Этот вариант подходит, если пользователи и их роли хранятся в корпоративном каталоге. В Keycloak нужно создать правило сопоставления ролей role-mapper.

1. Откройте User Federation -> Add new provider -> ldap.
2. Настройте подключение к AD/LDAP.
3. Откройте User Federation -> ldap -> Mappers -> Add mapper.
4. Создайте правило с именем role-mapper и типом role-ldap-mapper.
5. Пример параметров:
   • LDAP Roles DN: ou=groups,dc=demo,dc=zakroma,dc=ru
   • Role Name LDAP Attribute: cn
   • Role Object Classes: groupOfUniqueNames
   • Membership LDAP Attribute: uniqueMember
   • Membership Attribute Type: DN
   • Membership User LDAP Attribute: uid
   • Mode: LDAP_ONLY
   • User Role Retrieve Strategy: LOAD_ROLES_BY_MEMBER_ATTRIBUTE
   • Member-Of LDAP Attribute: memberOf
   • Client ID: zakroma
6. Выполните синхронизацию пользователей в User Federation -> ldap -> Settings -> Sync all users.

В inventories/<inventory>/group_vars/zakroma-disk.yml задайте роль, которая приходит из AD/LDAP:

Copy
1zakroma_disk_dsdrive:
2  users_sync:
3    user_role: "clouduser"
4    user_groups: ""
5    period: "60s"

13. Подключение групп из AD/LDAP

Этот вариант подходит, если пользователи и группы хранятся в корпоративном каталоге. В Keycloak нужно создать правило сопоставления групп group-mapper.

1. Откройте User Federation -> Add new provider -> ldap.
2. Настройте подключение к AD/LDAP.
3. Откройте User Federation -> ldap -> Mappers -> Add mapper.
4. Создайте правило с именем group-mapper и типом group-ldap-mapper.
5. Пример параметров:
   • LDAP Groups DN: ou=groups,dc=demo,dc=zakroma,dc=ru
   • Group Name LDAP Attribute: cn
   • Group Object Classes: groupOfUniqueNames
   • Membership LDAP Attribute: uniqueMember
   • Membership Attribute Type: DN
   • Membership User LDAP Attribute: uid
   • Mode: LDAP_ONLY
   • User Groups Retrieve Strategy: LOAD_GROUPS_BY_MEMBER_ATTRIBUTE
   • Member-Of LDAP Attribute: memberOf
   • Mapped Group Attributes: cn
   • Drop non-existing groups during sync: On
6. Выполните синхронизацию:
   • User Federation -> ldap -> Settings -> Sync all users
   • User Federation -> ldap -> Mappers -> group-mapper -> Sync LDAP Groups to Keycloak

В inventories/<inventory>/group_vars/zakroma-disk.yml задайте группу, которая приходит из AD/LDAP:

Copy
1zakroma_disk_dsdrive:
2  users_sync:
3    user_role: ""
4    user_groups: "zakroma-users-group"
5    period: "60s"

Параметры Закрома.Диск

14. Заполнение подключения к Keycloak

В inventories/<inventory>/group_vars/zakroma-disk.yml замените параметры Keycloak на значения вашего контура.

Copy
1zakroma_disk_dsdrive:
2  auth:
3    direct_grant:
4      # Нужно для WebDAV-клиентов и может использоваться Web UI без входа через браузер.
5      enabled: true
6      auth_key: "<DIRECT_GRANT_AUTH_KEY>"
7    keycloak:
8      url: "https://keycloak.zakroma.internal:8443"
9      realm: "zakroma"
10      clientId: "zakroma"
11      secret: "<CLIENT_SECRET>"
12  jwt:
13    algorithm: RS256
14    kid: "<KEY_ID>"
15    rsa_public_key: "<RSA_PUBLIC_KEY>"
16  users_sync:
17    # Заполните user_role или user_groups по выбранному варианту.
18    user_role: "clouduser"
19    user_groups: ""
20    period: "60s"

secret, kid и rsa_public_key необходимо взять из настроек приложения и ключей области пользователей в Keycloak. Не используйте демонстрационные значения из шаблонных inventory в production.