Настройка Keycloak

Закрома.Хранение может использовать Keycloak для аутентификации и авторизации пользователей в Admin UI и синхронизации пользователей для доступа к S3.

Поддерживаются версии Keycloak от 19.0 до 26.6.0.

Keycloak можно установить из поставки — см. Установку базового кластера с Keycloak — или использовать существующий сервис. В этой статье описана подготовка realm, клиента и пользователей в обоих случаях.

Подготовка realm и клиента

1. Выбор realm

В примере и готовых инструкциях используется realm master — так настроен realm из поставки files/keycloak/realm.json. Вы можете создать отдельный realm, например zakroma. Имя realm укажите в параметрах Закрома.Хранение.

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

Откройте Clients и нажмите Create client.
Создайте клиент с Client ID: zakroma.
Включите:
- Client authentication: On;
- Authorization: On;
- Standard flow: On;
- Direct access grants: On;
- Service accounts roles: On.
В Valid redirect URIs добавьте адрес Admin UI, например https://<ADMIN_UI_FQDN>:8443/*.

Direct access grants нужен для входа в Admin UI по логину и паролю, Service accounts roles — для синхронизации пользователей.

3. Права service account

Закрома.Хранение не требует административных прав на realm. Через service account клиента zakroma сервис читает realm, пользователей, группы и клиенты, а также завершает сессии пользователей.

Административные роли realm находятся у служебного клиента Keycloak, имя которого зависит от realm:

Realm	Клиент с административными ролями
`master`	`master-realm`
Отдельный realm, например `zakroma`	`realm-management`

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

Откройте Realm roles.
Создайте роль zakroma-realm-role.
Откройте Realm roles -> zakroma-realm-role -> Action -> Add associated roles.
Выберите фильтр Filter by clients.
Добавьте роли служебного клиента из таблицы выше — master-realm для realm master или realm-management для отдельного realm:
- view-realm;
- view-users;
- view-clients;
- query-groups;
- query-realms;
- query-users;
- query-clients;
- manage-users.
Добавьте роль account: view-groups.
Откройте Clients -> zakroma -> Service accounts roles.
Нажмите Assign role.
Выберите фильтр Filter by realm roles, отметьте zakroma-realm-role и нажмите Assign.

Роль manage-users нужна для завершения сессий пользователей, остальные роли дают доступ только на чтение.

Если административные права допустимы:

в realm master назначьте service account realm role admin — так настроен realm из поставки. Эта роль даёт права на все realm Keycloak, поэтому для общего Keycloak используйте гранулярные права;
в отдельном realm назначьте роль realm-management: realm-admin.

Не используйте bootstrap-администратора Keycloak в качестве service account.

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

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

5. Время жизни токена

Откройте Realm Settings -> Tokens и задайте Access Token Lifespan: 10 minutes.

6. Значения для Закрома.Хранение

Сохраните:

Client secret — Clients -> zakroma -> Credentials;
kid и публичный ключ активного ключа RS256 — Realm Settings -> Keys. Gateway проверяет по нему подпись токенов Keycloak.

Отбор пользователей

7. Выбор стратегии

Закрома.Хранение синхронизирует только разрешённых пользователей Keycloak — по ролям или группам.

Источник пользователей	Стратегия	Параметры Закрома.Хранение
Пользователи Keycloak	Client role `clouduser`	`sync_strategy: roles`, `permission.role: clouduser`
Пользователи Keycloak	Группа	`sync_strategy: groups`, `permission.group: <GROUP>`
AD/LDAP через User Federation	Роль из группы каталога	`sync_strategy: roles`, `permission.role: <ROLE>`
AD/LDAP через User Federation	Группа каталога	`sync_strategy: groups`, `permission.group: <GROUP>`

При sync_strategy: groups поддерживаются вложенные группы и перечисление нескольких групп через запятую — до 100 групп. Пользователь default_admin должен входить в выбранную роль или группу.

8. Пользователи Keycloak с ролью

Откройте Clients -> zakroma -> Roles и создайте роль clouduser.
Откройте Users -> Add user и создайте пользователя, например zakromaadmin.
В Users -> zakromaadmin -> Credentials -> Set password задайте пароль и выключите Temporary.
В Users -> zakromaadmin -> Role mapping -> Assign role выберите фильтр Filter by clients и назначьте роль clouduser клиента zakroma.

9. Пользователи Keycloak с группой

Откройте Groups и создайте группу, например zakromausers.
Добавьте в группу пользователей.

10. Подключение AD/LDAP

Откройте User Federation -> Add new provider -> ldap.
Укажите параметры подключения. Пример для OpenLDAP:
- Vendor: Other (для Active Directory — Active Directory);
- Connection URL: ldap://ldap.example.internal:389;
- Bind Type: simple;
- Bind DN: cn=admin,dc=example,dc=internal;
- Bind Credential: <LDAP_BIND_PASSWORD>;
- Edit Mode: UNSYNCED;
- Users DN: ou=users,dc=example,dc=internal;
- Username LDAP attribute: cn;
- RDN LDAP attribute: cn;
- UUID LDAP attribute: cn;
- User Object Classes: person, organizationalPerson.
Откройте User Federation -> ldap -> Mappers -> Add mapper и создайте маппер имени пользователя:
- Name: username-mapper;
- Mapper Type: user-attribute-ldap-mapper;
- User Model Attribute: username;
- LDAP Attribute: uid.

Значения DN, атрибутов и классов объектов зависят от схемы каталога.

11. Роли из AD/LDAP

Маппер сопоставляет группы каталога с client roles клиента zakroma.

В User Federation -> ldap -> Mappers -> Add mapper создайте маппер:
- Name: role-mapper;
- Mapper Type: role-ldap-mapper;
- LDAP Roles DN: ou=groups,dc=example,dc=internal;
- 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.
Выполните User Federation -> ldap -> Settings -> Sync all users.

В permission.role укажите имя роли, которое соответствует группе каталога.

12. Группы из AD/LDAP

В User Federation -> ldap -> Mappers -> Add mapper создайте маппер:
- Name: group-mapper;
- Mapper Type: group-ldap-mapper;
- LDAP Groups DN: ou=groups,dc=example,dc=internal;
- 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.
Выполните синхронизацию:
- User Federation -> ldap -> Settings -> Sync all users;
- User Federation -> ldap -> Mappers -> group-mapper -> Sync LDAP Groups to Keycloak.

Чтобы объединить несколько групп каталога, создайте в Keycloak корневую группу, например zakromausers, и укажите в поле Groups Path маппера значение /zakromausers/. Группы каталога будут созданы как дочерние, а в permission.group достаточно указать корневую группу. Поддерживается не более 100 вложенных групп на корневом уровне.

Параметры Закрома.Хранение

Для стандартной установки задайте параметры в блоке zakroma_storage_gateway.auth файла zakroma-storage.yml:

1  default_admin: zakromaadmin
2  auth:
3    auth_provider: keycloak
4    user_provider: "keycloak"
5    keycloak:
6      sync_strategy: roles
7      permission:
8        role: clouduser
9        group: zakromausers
10      connection_url: "https://keycloak.example.internal:8443"
11      realm: master
12      secret: "<KEYCLOAK_CLIENT_SECRET>"
13      client_id: zakroma
14      redirect_uri: "https://{{ zakroma_storage_admin.path }}:{{ zakroma_storage_admin.reverse_proxy.port }}"

redirect_uri — обязательный параметр: полный адрес Admin UI с протоколом и внешним портом.

Публичный ключ realm добавьте в zakroma_storage_gateway.jwt.keys отдельным элементом. Ключ innerkey с default: true сохраните:

1  jwt:
2    keys:
3      - kid: innerkey
4        # Значения innerkey из поставки или собственная пара ключей
5      - kid: "<KEYCLOAK_KID>"
6        rsa_public_key: "<KEYCLOAK_PUBLIC_KEY>"

В rsa_public_key укажите тело публичного ключа без строк -----BEGIN PUBLIC KEY----- и -----END PUBLIC KEY-----: роль добавляет их сама.

Пошаговая настройка приведена в Установке базового кластера с Keycloak. Для установки в Kubernetes имена параметров отличаются — см. Установку базового кластера с Keycloak в Kubernetes. Общие методы авторизации описаны в Настройке авторизации.

Смотрите также

Настройка авторизации

Установка базового кластера с Keycloak