06 Authorization

Provisioning аккаунтов и onboarding пользователей

Статус документа

Этот документ фиксирует первую рабочую модель завода пользователей в KSAILab после landed backend MR !10.

Она нужна для периода, когда:

Keycloak уже используется как IAM;
почта, внешние identity providers и self-service onboarding ещё не внедрены;
команде нужен быстрый и операционно понятный способ заводить преподавателей, группы и студентов;
frontend ещё догоняет новый backend contract, но backend onboarding endpoints уже существуют.

Связанные репозитории:

backend-ksailab
frontend-ksailab
keycloak-scripts-ksailab
docs-ksailab

Цель первой версии

Первая версия provisioning-инструмента должна решать три практические задачи:

быстро создать учётку преподавателя;
быстро создать одну или несколько учебных групп;
быстро создать студентов и сразу назначить их в выбранную группу.

При этом архитектура не должна мешать будущему переходу на:

LDAP;
SSO;
federation через Keycloak;
более сложные enterprise onboarding-потоки.

Базовые решения

Кто заводит аккаунты

В первой версии provisioning выполняет только admin.

Это означает:

teacher не создаёт других teacher accounts;
teacher не заводит student accounts;
все первичные credential-операции централизованы и хорошо аудируются.

Важно не смешивать этот provisioning path с bootstrap первого human admin:

первый human admin внутри realm ksailab создаётся отдельным Keycloak operator flow;
рекомендуемый bootstrap username для этого flow — platform-admin;
backend onboarding endpoints не должны создавать первого human admin сами;
ksailab-admin-service не заменяет human admin и остаётся только service account path.

Какой identifier используется

В v1 основным login identifier считается username.

Username:

используется для первого локального входа через Keycloak;
остаётся человекочитаемым;
может предлагаться frontend автоматически;
валидируется backend как уникальный.

Это осознанный pragmatic choice для первого этапа. В будущем migration to LDAP/SSO должен добавить отдельный внешний identity binding, но не меняет текущий onboarding UX на старте.

Как выдаются стартовые credentials

Почта и внешние сервисы сейчас не используются.

Поэтому для v1 принимается такой порядок:

пароль генерируется системой;
create-операция возвращает credential_receipt;
оператор раскрывает временный пароль только через отдельный consume flow;
receipt одноразовый и ограничен по TTL;
пользователь обязан сменить пароль при первом входе.

Это ключевое отличие от старой модели: temporary_password не должен описываться как обычное inline-поле ответа на create request.

Canonical onboarding API

Текущая рабочая onboarding-поверхность backend:

POST /api/v1/onboarding/teachers
POST /api/v1/onboarding/groups
POST /api/v1/onboarding/groups/{group_id}/teachers
POST /api/v1/onboarding/groups/{group_id}/students/bulk
POST /api/v1/onboarding/credentials/consume

Именно эти endpoints нужно считать canonical current contract для первой волны интеграции.

Provisioning-модель по сущностям

1. Teacher account provisioning

Teacher provisioning — это отдельная административная операция, а не обычный CRUD профиля.

Поток:

admin открывает Permissions -> Users;
вводит ФИО преподавателя;
frontend предлагает username по шаблону transliteration;
admin может подтвердить или поправить username;
backend проверяет уникальность;
backend создаёт account в Keycloak с realm role teacher;
backend включает required action на смену пароля при первом входе;
backend создаёт или связывает platform profile;
backend возвращает profile + credential_receipt;
оператор при необходимости вызывает POST /api/v1/onboarding/credentials/consume и получает временный пароль один раз.

Что не делает этот flow:

не рассылает приглашения;
не назначает преподавателя в группы автоматически;
не выдаёт bundles вручную в рамках этой операции.

2. Group provisioning

Group provisioning остаётся отдельной domain-операцией.

Поток:

admin открывает Education -> Groups;
создаёт одну группу или несколько групп подряд;
после создания при необходимости назначает teacher в group;
после этого group готова к приёму students.

Для первой версии допустим bulk UI с fan-out по single-create endpoint. Обязательный отдельный batch group API не требуется.

3. Teacher assignment to group

Назначение teacher в group — отдельная операция membership management.

Поток:

admin открывает group detail или group management panel;
выбирает преподавателя из active teacher accounts;
backend создаёт group-teacher relation;
преподаватель начинает видеть свой рабочий контур по ABAC.

Этот шаг сознательно отделён от teacher account creation, чтобы не смешивать identity creation и domain assignment.

4. Student bulk provisioning

Bulk student provisioning — это отдельная массовая операция, привязанная к конкретной группе.

Поток:

admin открывает onboarding action из Education -> Groups;
выбирает целевую группу;
вводит список студентов;
frontend предлагает usernames;
backend создаёт student accounts в Keycloak;
backend назначает всем студентам realm role student;
backend связывает созданные accounts с group membership;
для каждой успешно созданной записи backend возвращает отдельный credential_receipt;
UI показывает результаты batch-операции и построчные статусы успеха/ошибки.

Требования к batch-операции:

частичный успех допустим;
ошибки по отдельным строкам должны быть явными;
уже созданные аккаунты не должны теряться из-за одной невалидной записи;
общая партия не должна получать один общий пароль на всех;
результат должен быть пригоден для ручной передачи логинов и одноразового получения временного пароля по каждой записи.

Контур ответственности

Что делает Keycloak

создаёт identity;
хранит username;
хранит credentials;
выдаёт realm role;
хранит required actions вроде UPDATE_PASSWORD.

Что делает backend

оркестрирует provisioning-операцию;
проверяет права admin;
валидирует уникальность и бизнес-ограничения;
создаёт или связывает platform profile;
создаёт group memberships;
возвращает credential_receipt и consume-flow для UI;
позже сможет подменить локальный credential-flow на LDAP/SSO-aware flow без смены UI-логики.

Что делает frontend

собирает удобную форму для оператора;
показывает предложенный username;
отображает результаты batch-операции;
не хранит пароль дольше, чем нужно для одноразового показа;
не принимает окончательных auth-решений сам.

Runtime capabilities для onboarding-операций

Первая landed версия onboarding уже опирается на явные backend capability keys:

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

Именно этот набор сейчас составляет минимальный runtime contract для первой фронтовой интеграции.

В будущем он может быть расширен и сведен с более общим catalog-driven permission model, но текущую реализацию нужно документировать именно так.

Целевые административные экраны

`Permissions -> Users`

Этот экран в первой версии должен отвечать за:

создание teacher accounts;
просмотр teacher/admin accounts;
деактивацию аккаунта;
запуск one-time credential handoff;
просмотр статуса "должен сменить пароль".

`Education -> Groups`

Этот экран должен отвечать за:

создание groups;
bulk creation groups через UI fan-out при необходимости;
назначение teacher к group;
переход к roster/onboarding студентов.

`Education -> Groups -> Group Detail`

Этот экран должен стать точкой для:

bulk create students;
просмотра текущего состава группы;
повторного provisioning отдельных students при ошибках;
управления membership.

Bridge с текущим backend

В старом backend уже были полезные legacy-контракты вроде /users/create, /users/bulk/create-students и /groups/management/*.

Но для актуальной документации KSAILab их нельзя описывать как основной текущий onboarding contract.

Правильная формулировка такая:

legacy endpoints могут оставаться переходным transport слоем внутри миграции;
canonical current onboarding API — это POST /api/v1/onboarding/*;
локальная password semantics больше не должна определять продуктовую документацию.