06 Authorization

Миграция с Zitadel на Keycloak

Зачем нужен этот документ

Документ фиксирует, что именно в архитектуре и документации меняется при отказе от Zitadel и переходе на Keycloak.

Это не просто переименование IAM-компонента. Меняется вся рабочая модель:

identity provider;
auth flow;
contract between backend and frontend;
permission delivery model;
подход к user lifecycle;
способ масштабирования новых прав и экранов.

Что заменяется принципиально

Было в старой документации

Zitadel как auth service;
frontend или backend, работающий с flow старой модели;
общий разговор про роли и права без явного capability catalog;
отсутствие отдельного frontend-раздела как потребителя auth-модели.

Становится в новой документации

Keycloak как единственный IAM;
backend-owned browser session flow;
capability catalog как базовый механизм UI permissions;
backend как PEP/PDP для ABAC;
frontend как отдельный архитектурный участник permission-модели.

Что надо вычистить из реализации и документации

Legacy-предположения

backend сам логинит пользователя по паролю;
backend сам выпускает access/refresh JWT как целевую модель;
роль читается из локального профиля без IAM-context;
sub трактуется как локальный integer id;
меню и экраны живут на if role === ...;
permissions pages не имеют явного capability contract.

Что должно появиться вместо этого

frontend -> backend /api/v1/auth/login;
Keycloak -> backend /api/v1/auth/callback;
opaque browser cookie + server-side auth session + GET /api/v1/auth/me bootstrap;
realm roles в Keycloak;
/auth/me с capabilities;
binding между Keycloak identity и платформенным профилем;
capability catalog;
permission bundles и assignments в платформе;
resource-scoped ABAC в backend;
platform UI -> backend -> Keycloak Admin API для user lifecycle.

Потоки работ в миграции

1. Документация

заменить базовый auth-источник истины в 06-authorization;
актуализировать backend docs под реальный код и целевую роль backend;
добавить frontend docs и permission surface;
использовать capability catalog как центральный словарь прав.

2. Keycloak

описать realm;
описать clients;
описать realm roles;
описать protocol mappers;
описать admin API integration;
зафиксировать transition vs target ownership model для browser auth clients;
отделить realm-as-code от platform permission administration.

3. Backend

убрать локальную целевую auth-модель из архитектуры;
ввести principal + capability layer;
оставить ABAC на платформенных данных;
подготовить migration path от локального users.id.

4. Frontend

уйти от hardcoded/mock auth assumptions;
стартовать browser login через backend, а не через direct frontend-owned Keycloak flow;
получать права через /auth/me;
строить guards и меню от capabilities;
зафиксировать, какие экраны уже реальные, а какие пока шаблонные.

5. Administration model

зафиксировать, что capability keys не создаются из UI;
bundles и assignments живут в БД платформы;
Keycloak хранит только identity и базовые realm roles;
permissions section фронта становится точкой ежедневного администрирования.

6. Provisioning model

зафиксировать отдельный onboarding-flow для teachers, groups и students;
убрать предположение, что user creation равен локальной записи с паролем в БД;
перевести reset/init password semantics на Keycloak-first orchestration;
использовать старый frontend только как UX-референс, а не как auth-source of truth.

Инструменты, которые должны появиться в реализации

В IAM-контуре

Keycloak realm config;
clients and redirect URIs;
realm roles;
admin service account;
bootstrap/import strategy.

В backend-контуре

OIDC/JWKS validation;
Keycloak Admin API client;
profile binding strategy;
capability registry;
bundle and assignment storage;
policy/dependency layer;
/auth/me capability manifest.

Во frontend-контуре

bootstrap auth state через backend;
browser login entry через backend;
capability-based navigation rendering;
route guards на capabilities;
component-level permission helpers.

Определение готовности миграции в документации

Миграция документации считается достаточной для старта реализации, когда:

Zitadel больше не описывается как целевая auth-система в ключевых архитектурных разделах;
Keycloak описан как новый IAM и источник ролей;
Keycloak не описывается как primary store для полного каталога platform permissions;
capability catalog существует и связан с текущим frontend;
frontend permissions описаны не абстрактно, а по конкретным разделам и маршрутам;
backend описан как policy enforcement layer, а не как legacy auth-server;
команда может без дополнительных продуктовых решений назвать инструменты и контракты для следующего инженерного этапа.

Что ещё останется после этой итерации

Даже после обновления 02, 06, 09 и общего detail/README.md останутся разделы, где Zitadel ещё нужно будет заменить в следующем проходе:

инфраструктурные документы;
Kubernetes namespace docs;
сетевые потоки;
части draw.io-схем.

Это не блокирует текущее архитектурное проектирование, если источником истины по auth и permission-модели остаются обновлённые разделы 02, 06 и 09.

К ним нужно читать вместе:

Матрица прав текущего фронта

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