Keycloak, LDAP и OAuth

Этот чеклист настраивает Keycloak для Selena через Keycloak Admin Console. Keycloak может быть внешним customer-managed сервисом или компонентом, установленным в тот же Kubernetes cluster. Selena Helm charts не создают realm, users, groups, clients и LDAP federation.

1. Создайте или выберите realm

Чеклист:

• Realm называется selena или все Selena values адаптированы под другое имя realm.
• Browser-facing issuer стабилен до создания clients.
• Issuer в tokens совпадает с настройками CM, IDE, AI, MCP и Grafana.

В Keycloak Admin Console:

1. Откройте Keycloak Admin Console.
2. В левом верхнем углу откройте realm selector.
3. Нажмите Create realm.
4. В поле Realm name введите selena.
5. Убедитесь, что Enabled включен.
6. Нажмите Create.

Проверьте issuer:

1. Перейдите в Realm settings.
2. Откройте General.
3. Найдите ссылку OpenID Endpoint Configuration.
4. Откройте ее и проверьте поле issuer.

Ожидаемое значение:

{keycloak_public_url}/realms/selena

Например:

https://keycloak.example.com/realms/selena

Это значение должно совпадать с {keycloak_public_url}/realms/selena во всех Selena values.

2. Настройте LDAP или Active Directory federation

Пропустите этот раздел только если все users локальные в Keycloak.

Полезные официальные справки:

Документация	Когда открыть
Keycloak Server Administration Guide: LDAP and Active Directory	Основная справка по настройке User federation в Keycloak: LDAP provider, storage/edit mode, sync, LDAPS, connection pool и troubleshooting.
Keycloak Server Administration Guide: LDAP mappers	Когда настраиваете mapper для групп, user attributes или нестандартной LDAP/AD schema.
OpenLDAP Administrator's Guide	Если LDAP server построен на OpenLDAP и нужно уточнить DN, suffix, schema, access rules, replication или диагностику LDAP server-side.
Microsoft: Configure LDAPS for Active Directory Domain Services	Если используется Microsoft AD и Keycloak должен подключаться по LDAPS (ldaps://...:636).

Чеклист:

• Keycloak может подключиться к LDAP/AD.
• Bind DN имеет read-only доступ к users и groups.
• Username в Keycloak совпадает с username, которым пользователь будет входить в Selena UI.
• Group membership виден в Keycloak.

В Keycloak Admin Console:

1. Выберите realm selena.
2. Перейдите в User federation.
3. Нажмите Add provider.
4. Выберите ldap.
5. Заполните connection и user lookup settings.
6. Сохраните provider.

Типовые настройки LDAP/AD provider:

Setting	Пример	Комментарий
Vendor	Active Directory или Other	Выберите closest match.
Connection URL	ldaps://ad.example.com:636	Для production используйте TLS.
Bind type	simple	Обычно достаточно для service account.
Bind DN	CN=svc-keycloak,OU=Service Accounts,DC=example,DC=com	Read-only service account.
Bind credential	password из secret-management процесса заказчика	Не храните пароль в документации или ConfigMap.
Users DN	OU=Users,DC=example,DC=com	Base DN для user search.
Username LDAP attribute	sAMAccountName или uid	Это станет Keycloak username.
RDN LDAP attribute	cn	Обычно cn, но зависит от directory schema.
UUID LDAP attribute	objectGUID или entryUUID	Для AD обычно objectGUID, для LDAP часто entryUUID.
User object classes	person, organizationalPerson, user или customer schema	Должно соответствовать directory schema.
Edit mode	READ_ONLY	Рекомендуется для enterprise LDAP/AD.
Import users	ON	Рекомендуется для стабильного lookup и membership sync.
Sync registrations	OFF	Обычно users создаются в LDAP/AD, не через Keycloak.

Добавьте group mapper:

1. Откройте созданный LDAP provider.
2. Перейдите во вкладку Mappers.
3. Нажмите Add mapper.
4. Выберите mapper type group-ldap-mapper.
5. Заполните group lookup settings.
6. Сохраните mapper.

Типовые настройки group mapper:

Setting	Пример	Комментарий
Mapper type	group-ldap-mapper	Читает LDAP/AD groups в Keycloak groups.
LDAP Groups DN	OU=Groups,DC=example,DC=com	Base DN для group search.
Group name LDAP attribute	cn	Имя группы в Keycloak.
Group object classes	group или groupOfNames	Для AD обычно group.
Membership LDAP attribute	member	Атрибут, где group хранит members.
Membership attribute type	DN	Обычно DN.
User roles retrieve strategy	LOAD_GROUPS_BY_MEMBER_ATTRIBUTE	Читает groups через membership attribute.
Preserve group inheritance	ON	Сохраняет иерархию groups, если она есть.
Mode	READ_ONLY	Рекомендуется для enterprise LDAP/AD.

Синхронизируйте users и groups:

1. Вернитесь в User federation.
2. Откройте LDAP provider.
3. В Action выберите Sync all users.
4. Откройте group mapper.
5. В Action выберите Sync LDAP groups to Keycloak.

Проверьте в UI:

1. Users -> найдите LDAP/AD user -> вкладка Groups.
2. Groups -> откройте imported group -> вкладка Members.

Если groups не появились, проверьте LDAP Groups DN, membership attribute и права bind account на чтение groups.

3. Создайте группы

Чеклист:

• Созданы CM admin/viewer groups.
• Созданы Grafana groups.
• Созданы business groups, которые будут давать доступ к данным в Selena Engine.
• В CM values используются full group paths.

В Keycloak Admin Console:

1. Перейдите в Groups.
2. Для top-level group нажмите Create group.
3. Для nested group откройте parent group и используйте Subgroups -> Create group.
4. После создания добавляйте users через Users -> user -> Groups -> Join group.

Рекомендованный baseline:

Group path	Для чего
/cm/admins	Полное администрирование Selena Cluster Manager. Users из этой группы могут выполнять административные операции CM.
/cm/role-admins	Управление Selena roles/grants через CM без полного cluster admin-доступа.
/cm/viewers	Read-only доступ к CM для просмотра состояния и диагностики.
/grafana/admins	Grafana Admin. Используется Grafana OAuth role mapping.
/grafana/viewers	Grafana Viewer. Используется Grafana OAuth role mapping.
/ldap/selena-readers	Пример business-группы для LDAP/AD users, которым нужен read-доступ к данным в Selena Engine. В CM values эта group path маппится на external group, а затем на Selena role/grants.
/ldap/selena-writers	Пример business-группы для LDAP/AD users, которым нужен write-доступ к данным в Selena Engine. Обычно этой группе назначают более широкие Selena privileges, чем reader-группе.
/local/selena-readers	Пример business-группы для локальных Keycloak users, если заказчик использует local users для demo, service acceptance или отдельных внутренних учеток. Смысл такой же: membership дает доступ к данным через CM mapping и Selena roles.

Группы /ldap/... и /local/... в таблице являются примерами. В production используйте реальные customer group paths, например /data/finance/readers или /analytics/sales/writers. Важно, чтобы path был стабильным и совпадал с mapping в selena-cm-values.yaml.

В CM этот mapping задается в docs-external/values-minimal/selena-cm-values.yaml, в блоке extraEnv -> SPRING_APPLICATION_JSON. Там находятся две разные настройки:

Настройка	Что означает
cm.identity.external-groups.mappings	Keycloak group path -> Selena external group name. Это business/data-access mapping: какие Keycloak groups CM синхронизирует для доступа к данным в Selena Engine.
cm.security.group-role-mappings	Keycloak group path -> CM API role. Это access mapping для самого Selena Cluster Manager: кто будет CM admin, role admin или viewer.

Ключи вида [/ldap/selena-readers] должны совпадать с full group path в Keycloak. Значения вроде ldap_selena_readers или cm_admin - это уже имена, которые понимает CM: external group name для Engine-доступа или CM role для доступа к CM API. Подробный RBAC-чеклист находится в IDE, AI/MCP, RBAC, пользователи и direct SQL.

Эти business-группы управляют именно доступом к данным в Selena Engine. Сама группа в Keycloak еще не выдает privilege автоматически: администратор сначала указывает full group path в CM values, затем через CM API создает Selena roles, назначает им privileges и привязывает roles к mapped external groups. После этого scheduled sync CM читает membership из Keycloak и поддерживает актуальные пользовательские права в Selena.

Разделение /ldap/... и /local/... не является техническим требованием. Это понятный пример, который помогает не смешивать LDAP/AD-backed users и локальных Keycloak users при приемочном тестировании. Если у заказчика уже есть свои группы в AD/Keycloak, используйте их реальные paths.

Для local Keycloak users:

1. Перейдите в Users.
2. Нажмите Add user.
3. Заполните Username, First name, Last name, Email.
4. Включите Email verified, если email уже проверен customer process-ом.
5. Сохраните user.
6. Откройте вкладку Credentials.
7. Нажмите Set password.
8. Введите password и выключите Temporary, если user не должен менять пароль при первом входе.
9. Откройте вкладку Groups.
10. Нажмите Join group и выберите нужные groups.

Для LDAP/AD users профиль и password приходят из federation. Membership можно вести в LDAP/AD или назначать дополнительные Keycloak-local groups, если это разрешено политикой заказчика.

4. Создайте OIDC clients

Чеклист:

• Созданы все required clients.
• Client secrets сохранены в Kubernetes Secret или external secret store.
• Redirect URIs используют финальные public URLs.
• User-facing clients имеют groups mapper.
• Tokens, которые проверяют Selena services, имеют audience selena-engine.

В Keycloak Admin Console:

1. Перейдите в Clients.
2. Нажмите Create client.
3. Client type выберите OpenID Connect.
4. Введите Client ID.
5. Нажмите Next.
6. Включите Client authentication для confidential clients.
7. Настройте Authentication flow.
8. Нажмите Next.
9. Заполните Valid redirect URIs, Valid post logout redirect URIs и Web origins, если они нужны client-у.
10. Нажмите Save.
11. Для confidential client откройте вкладку Credentials и скопируйте Client secret в secret-management процесс.

Required clients:

Client ID	Как настроить в Keycloak UI
selena-engine	Client authentication: ON. Standard flow: ON. Direct access grants: ON. Service accounts: OFF. Valid redirect URIs: {cm_public_url}/*. Web origins: {cm_public_url}.
selena-cluster-manager-api	Client authentication: ON. Standard flow: OFF. Direct access grants: OFF. Service accounts: ON. Browser redirect URIs не нужны.
selena-ide	Client authentication: ON. Standard flow: ON. Direct access grants: OFF. Service accounts: OFF. Valid redirect URIs: {ide_public_url}/oauth2callback, {ide_public_url}/*. Web origins: {ide_public_url}.
selena-ide-service	Client authentication: ON. Standard flow: OFF. Direct access grants: OFF. Service accounts: ON. Browser redirect URIs не нужны.
selena-ai	Client authentication: ON. Standard flow: ON. Direct access grants: OFF. Service accounts: OFF. Valid redirect URIs: {ai_public_url}/api/v1/auth/callback, {ai_public_url}/*. Web origins: {ai_public_url}, {ide_public_url}.
grafana	Client authentication: ON. Standard flow: ON. Direct access grants: OFF. Service accounts: OFF. Valid redirect URIs: {grafana_public_url}/login/generic_oauth, {grafana_public_url}/*. Valid post logout redirect URIs: {grafana_public_url}/login. Web origins: {grafana_public_url}.

{ai_public_url} не обязан быть отдельным публичным порталом. Это URL, который browser может загрузить внутри IDE iframe. Его можно опубликовать как отдельный host, например https://ai.example.com, или как path под IDE/API gateway, если reverse proxy маршрутизирует этот path в AI frontend Service.

Optional client selena-ai-service создавайте только если ваш deployment profile явно использует AI service-to-service calls в CM. В текущем minimal AI chart используется browser client selena-ai и trusted IDE service client selena-ide-service; отдельного Secret для selena-ai-service в minimal values нет.

Сохраните client secrets в Kubernetes Secrets из Values, Secrets и Images:

Client ID	Secret key
selena-engine	CM_KEYCLOAK_LOGIN_CLIENT_SECRET
selena-cluster-manager-api	CM_KEYCLOAK_ADMIN_CLIENT_SECRET
selena-ide	IDE_KEYCLOAK_CLIENT_SECRET
selena-ide-service	IDE_SERVICE_CLIENT_SECRET
selena-ai	AI_BACKEND_AUTH_CLIENT_SECRET
grafana	selena-grafana-keycloak-client/client-secret

5. Добавьте token mappers

Token mappers нужны, чтобы приложения Selena получали из Keycloak token те claims, по которым они узнают пользователя, группы и назначение token. Keycloak хранит эту информацию в своем user/group model, но приложение видит только то, что попало в issued token. Поэтому mapper здесь означает "положить конкретное поле из Keycloak в конкретный claim access token".

Что именно нужно получить в access token:

Claim	Что маппим	Зачем нужно
preferred_username	Keycloak user username.	Selena components используют это как стабильное имя пользователя. Обычно claim уже приходит через built-in profile scope, но его надо проверить.
groups	Полный список Keycloak groups пользователя в виде full paths, например /cm/admins, /ldap/selena-readers или /data/finance/readers.	CM использует group paths для CM roles и для mapping business groups на Selena roles/grants. Full path нужен, чтобы не перепутать одинаковые leaf names в разных ветках.
aud	Audience selena-engine.	Selena services отклоняют token, который не предназначен для Selena audience. Это защита от использования token, выпущенного для чужого client-а.

Preferred username mapper

Сначала проверьте, что client получает built-in client scope profile:

1. Откройте Clients.
2. Выберите user-facing client, например selena-engine.
3. Откройте вкладку Client scopes.
4. Убедитесь, что profile назначен как default scope.

Если preferred_username не появляется в access token, добавьте mapper:

1. Откройте Client scopes.
2. Создайте или выберите scope, который назначен Selena clients.
3. Откройте Mappers.
4. Нажмите Add mapper.
5. Выберите mapper type User Property.

Settings:

Field	Value
Name	preferred_username
Property	username
Token claim name	preferred_username
Claim JSON Type	String
Add to access token	ON
Add to ID token	ON
Add to userinfo	ON

Groups mapper

Рекомендуемый вариант: создать общий client scope, например selena-groups, и назначить его всем user-facing clients.

В Keycloak Admin Console:

1. Перейдите в Client scopes.
2. Нажмите Create client scope.
3. Name: selena-groups.
4. Type: Default или Optional, в зависимости от политики заказчика. Для Selena проще использовать Default, чтобы claim всегда был в token.
5. Сохраните scope.
6. Откройте scope selena-groups.
7. Перейдите в Mappers.
8. Нажмите Add mapper.
9. Выберите mapper type Group Membership.

Settings:

Field	Value
Name	groups
Token claim name	groups
Full group path	ON
Add to access token	ON
Add to ID token	ON, если UI читает ID token
Add to userinfo	ON, если приложение вызывает userinfo

Назначьте scope selena-groups user-facing clients:

1. Откройте Clients.
2. Выберите client.
3. Откройте Client scopes.
4. Нажмите Add client scope.
5. Выберите selena-groups.
6. Назначьте как Default, если claim должен приходить всегда.

User-facing clients:

selena-engine
selena-ide
selena-ai
grafana

Audience mapper

Audience mapper добавляет selena-engine в claim aud. Это нужно для tokens, которые проверяются Selena services.

Рекомендуемый вариант: создать client scope selena-audience.

В Keycloak Admin Console:

1. Перейдите в Client scopes.
2. Нажмите Create client scope.
3. Name: selena-audience.
4. Type: Default.
5. Сохраните scope.
6. Откройте scope selena-audience.
7. Перейдите в Mappers.
8. Нажмите Add mapper.
9. Выберите mapper type Audience.

Settings:

Field	Value
Name	selena-engine-audience
Included client audience	selena-engine
Add to access token	ON
Add to ID token	OFF, если нет отдельного требования

Назначьте scope selena-audience этим clients:

selena-engine
selena-ide
selena-ai
selena-ide-service

Если в вашем deployment profile используется optional selena-ai-service, тоже назначьте ему selena-audience.

Проверка mappers в Keycloak UI

1. Откройте Clients.
2. Выберите client, например selena-engine.
3. Откройте вкладку Client scopes.
4. Откройте Evaluate.
5. Выберите test user, который состоит в Selena groups.
6. Нажмите generate/evaluate token.
7. Откройте generated access token.

Проверьте:

Claim	Ожидаемо
preferred_username	Keycloak username test user-а.
groups	Содержит full paths, например /cm/admins или /ldap/selena-readers.
aud	Содержит selena-engine.

Если groups содержит только selena-readers без parent path, включите Full group path в Group Membership mapper. Если aud не содержит selena-engine, проверьте Audience mapper и назначение client scope на client.

6. Дайте CM read-доступ к Keycloak Admin API

Чеклист:

• selena-cluster-manager-api имеет service account.
• Service account может читать realm users и groups.
• Service account не имеет broad write-admin ролей без approval.

В Keycloak Admin Console:

1. Перейдите в Clients.
2. Откройте selena-cluster-manager-api.
3. Убедитесь, что Service accounts включен.
4. Откройте вкладку Service account roles.
5. Нажмите Assign role.
6. В фильтре выберите roles клиента realm-management.
7. Назначьте только read/query roles из таблицы ниже.

Required roles:

Role	Зачем
view-realm	Читать metadata realm.
view-users	Читать users.
query-users	Искать users по username.
query-groups	Искать groups и membership.

Если в CM на экране Группы и SQL роли виден warning, что CM не видит группы Keycloak, сначала проверьте именно эти service account roles у selena-cluster-manager-api. Пользовательская роль cm_admin даёт права внутри CM, но не заменяет технический read-доступ backend-а к Keycloak Admin API.

Не назначайте manage-users, manage-realm, realm-admin или другие write roles без отдельного security approval.

7. Настройте Grafana roles

Чеклист:

• Созданы realm roles grafana_admin и grafana_viewer.
• /grafana/admins получает grafana_admin.
• /grafana/viewers получает grafana_viewer.
• Grafana OAuth config использует strict role mapping.
• Пользователь без Grafana role не может войти в Grafana.

Создайте realm roles:

1. В Keycloak Admin Console откройте Realm roles.
2. Нажмите Create role.
3. Создайте role grafana_admin.
4. Повторите для grafana_viewer.

Назначьте roles группам:

1. Откройте Groups.
2. Выберите /grafana/admins.
3. Откройте Role mapping.
4. Нажмите Assign role.
5. Выберите realm role grafana_admin.
6. Повторите для /grafana/viewers и role grafana_viewer.

Проверка:

1. Добавьте test user в /grafana/viewers.
2. Зайдите в Grafana и проверьте Viewer.
3. Переместите user в /grafana/admins.
4. Выйдите и войдите снова; проверьте Admin.
5. Уберите обе Grafana groups.
6. Выйдите и войдите снова; доступ должен быть запрещен.

8. Добавьте первого CM admin

Чеклист:

• Хотя бы один human user состоит в /cm/admins.
• Этот user может войти в CM после установки CM.
• Token содержит group claim.

В Keycloak Admin Console:

1. Перейдите в Users.
2. Найдите нужного user.
3. Откройте вкладку Groups.
4. Нажмите Join group.
5. Выберите /cm/admins.
6. Сохраните membership.

После установки CM выполните login в CM под этим user и проверьте, что user получил роль cm_admin.