06 Authorization

Каталог capabilities

Назначение

Каталог capabilities задаёт единый словарь платформенных прав для:

пунктов меню;
маршрутов и страниц;
component-level visibility;
action buttons и административных операций;
серверного permission bootstrap через backend-owned GET /api/v1/auth/me.

Важно: capabilities не заменяют ABAC. Они отвечают за глобальную видимость и право инициировать действие. Доступ к конкретному ресурсу backend проверяет дополнительно. Важно отдельно: capability catalog не описывает ownership OIDC clients, code exchange или browser session lifecycle. Это другой слой auth-контракта.

Где каталог живёт

Capability catalog является версионируемым контрактом.

Он должен существовать синхронно:

в backend как capability registry;
в документации как canonical human-readable реестр.

Platform UI использует этот каталог, но не создаёт новые capability keys самостоятельно. Keycloak также не должен использоваться как primary store этого каталога.

Текущая backend read-only delivery surface для этого каталога:

GET /api/v1/permissions/catalog — capability registry snapshot;
GET /api/v1/permissions/role-mappings — starter role mappings;
GET /api/v1/permissions/bundles — starter bundle composition.

Это admin read layer для Permissions section, а не замена bootstrap-контракту GET /api/v1/auth/me.

Принципы именования

формат: <section>.<resource>.<action>;
ключ должен быть стабильным и человекочитаемым;
capability должен описывать платформенное право, а не внутреннюю техническую реализацию.

Базовый каталог

Capability	Назначение	Тип	Роли по умолчанию	Starter bundles	Комментарий
`home.read`	Доступ к главной странице	Global	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Базовый вход в платформу
`inbox.read`	Доступ к входящим уведомлениям	Global	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Пока UI-оболочка
`profile.read`	Просмотр собственного профиля	Global + self	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Только для себя
`settings.read`	Доступ к общим настройкам	Global + self	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Базовый settings shell
`settings.security.read`	Просмотр раздела безопасности	Global + self	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Персональный security section
`settings.security.manage`	Изменение настроек безопасности	Self	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Персональный security action scope
`settings.notifications.read`	Просмотр настроек уведомлений	Global + self	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Персональный notifications section
`settings.notifications.manage`	Изменение настроек уведомлений	Self	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Персональные настройки
`modules.read`	Доступ к разделу модулей	Global	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Текущий экран обзорный
`system.read`	Доступ к разделу системы и интеграций	Global	admin	`admin.base`	Сейчас следует считать admin-only
`education.read`	Доступ к разделу образования	Global	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Родительский раздел
`education.courses.read`	Просмотр учебных курсов	Global	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Для teacher/student дальше включается ABAC
`education.courses.manage`	Создание и изменение учебных курсов	Global + resource	admin, teacher	`admin.base`, `teacher.base`	Teacher только для своих сущностей
`education.groups.read`	Просмотр учебных групп	Global	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Для student фактически через assignment scope
`education.groups.manage`	Создание и изменение учебных групп	Global + resource	admin, teacher	`admin.base`, `teacher.base`	Teacher только в своём контуре после v1 onboarding
`education.groups.members.read`	Просмотр состава группы	Global + resource	admin, teacher	`admin.base`, `teacher.base`	Используется для roster и membership UI
`education.groups.members.manage`	Назначение teacher и onboarding студентов в группу	Global + resource	admin	`admin.base`	В первой версии bulk student onboarding и teacher assignment выполняет только admin
`education.library.read`	Просмотр библиотеки материалов	Global + resource	admin, teacher, student	`admin.base`, `teacher.base`, `student.base`	Доступ к конкретным материалам проверяется отдельно
`education.question_bank.read`	Просмотр банка вопросов	Global + resource	admin, teacher	`admin.base`, `teacher.base`	Может быть расширено позже
`education.question_bank.manage`	Управление банком вопросов	Global + resource	admin, teacher	`admin.base`, `teacher.base`	Teacher только по allowed scope
`monitoring.read`	Доступ к разделу мониторинга	Global	admin	`admin.monitoring`	Родительский раздел
`monitoring.logs.read`	Просмотр логов и аудитных событий	Global	admin	`admin.monitoring`	Обычно admin/support
`monitoring.system_info.read`	Просмотр системной информации	Global	admin	`admin.monitoring`	Обычно admin/support
`monitoring.db_diagnostics.read`	Просмотр диагностики БД	Global	admin	`admin.monitoring`	Обычно admin/platform engineer
`monitoring.k8s_diagnostics.read`	Просмотр K8s-диагностики	Global	admin	`admin.monitoring`	Обычно admin/platform engineer
`permissions.read`	Доступ к разделу управления доступами	Global	admin	`admin.permissions`	Родительский раздел
`permissions.users.read`	Просмотр пользователей и их ролей	Global	admin	`admin.permissions`	Для admin UI и аудита
`permissions.users.manage`	Создание и изменение teacher/admin accounts	Global	admin	`admin.permissions`	Делегируется в Keycloak Admin API
`permissions.users.credentials.manage`	Сброс стартового пароля и credential lifecycle	Global	admin	`admin.permissions`	Включает повторную выдачу временного пароля и re-arm первого входа
`permissions.groups.read`	Просмотр permission-групп и bundles	Global	admin	`admin.permissions`	Базовый список bundles и assignments
`permissions.groups.manage`	Управление permission-группами и bundles	Global	admin	`admin.permissions`	Основная ежедневная админка bundles
`permissions.roles.read`	Просмотр platform role mappings	Global	admin	`admin.permissions`	Не равно realm role editing напрямую
`permissions.roles.manage`	Управление role mappings и grants	Global	admin	`admin.permissions`	Делегируется через backend orchestration

Runtime-only baseline рядом с каталогом

Текущий backend registry уже хранит и отдельный landed runtime baseline первой auth/onboarding wave:

auth.bootstrap.read
onboarding.teacher.create
onboarding.group.create
onboarding.group.assign_teacher
onboarding.student.bulk_create
onboarding.credentials.consume

В read-only backend contract эти keys могут публиковаться рядом с базовым catalog snapshot как runtime_baseline, но это не означает, что starter bundles уже переведены на полный DB-driven permission admin model.

Что делать с новыми фичами

Для любой новой фичи порядок должен быть таким:

Добавить capability в каталог.
Зафиксировать, это global capability или resource-scoped действие.
Обновить матрицу прав фронта.
Добавить backend policy rule.
Добавить capability в /auth/me, если фича доступна роли или группе пользователей.

Именно эта последовательность даёт возможность расширять систему доступа за полчаса, а не переписывать логику вручную по всему стеку.

Для onboarding первой версии это означает:

teacher account lifecycle опирается на permissions.users.*;
group roster и student onboarding опираются на education.groups.members.*;
сам факт существования teacher или student realm role не считается достаточным без соответствующих platform capabilities.
frontend не должен делать вывод о доступе только по наличию client-side JWT claims без backend bootstrap через /auth/me.

Lifecycle capability

Добавление

Новая capability добавляется только через:

backend registry;
этот каталог;
backend policy usage;
frontend matrix при необходимости.

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

После появления capability в каталоге platform admin может без релиза:

добавить её в существующий bundle;
создать новый bundle;
выдать bundle пользователю или группе;
наложить allow/deny override.

Удаление

Capability сначала помечается как deprecated, затем выводится из bundles и только после очистки использования удаляется окончательно.

Подробная operating model:

Что не делать

Не кодировать доступ только через role === ....
Не заводить ad-hoc поля вида canSeeMonitoring, если им можно дать нормальный capability key.
Не смешивать глобальную видимость страницы и доступ к конкретному ресурсу в одно право.
Не считать capability достаточным без backend ABAC-проверки.
Не пытаться хранить полный каталог capabilities в Keycloak.
Не трактовать capability catalog как описание browser login flow или client ownership в Keycloak.

Модель администрирования capabilities

Lab Deployments — Документация компонента