Аутентификация и роли¶

Роли и интеграция с Keycloak¶

Как устроена аутентификация¶

Собственной базы пользователей и страницы входа у Cryptex нет. За аутентификацию отвечает внешний Keycloak, а само приложение работает по модели stateless JWT.

Веб-интерфейс проходит вход в Keycloak, получает токен и передаёт его backend'у в каждом запросе в заголовке Authorization: Bearer <token>.

Из токена backend читает два значения:

Организацию (арендатора) — из claim groups. Берётся первая группа пользователя, ведущий символ / отбрасывается. По этому имени изолируются данные: пользователь видит только проекты и файлы своей организации. Поэтому каждый пользователь должен состоять в группе, соответствующей его компании; если групп несколько, арендатора определяет первая.
Роли — из claim realm_access.roles (realm-роли Keycloak).

Если организацию из токена определить нельзя (нет группы) или токен отсутствует, запрос отклоняется с кодом 401.

Какие роли есть в системе¶

Роль пользователя передаётся в токене в поле realm_access.roles. Система различает три роли:

Роль	Доступные действия
`viewer`	Только чтение: просмотр проектов, APK, конфигураций, статусов и скачивание результата (GET). Без создания, изменения и удаления.
`user`	Чтение, создание и изменение: проекты, загрузка APK, запуск и настройка защиты (GET, POST, PUT, PATCH). Без удаления.
`admin`	Полный доступ, включая удаление проектов (GET, POST, PUT, PATCH, DELETE).

Разграничение проверяется по операциям, а не по страницам:

Чтение (список и карточки проектов, APK, конфигурации шифрования, статусы, скачивание защищённого файла) — доступно всем трём ролям; для GET-запросов роль не проверяется, достаточно действительного токена и членства в группе организации.
Изменение (создание проекта, загрузка APK, запуск шифрования, правка проекта, загрузка сертификата подписи) — требуется роль user или admin.
Удаление проекта — требуется роль admin. Это единственная операция, для которой роли user недостаточно.

При отсутствии нужной роли операция изменения или удаления возвращает 403. Роль viewer в проверках записи не участвует, поэтому её обладатель ограничен чтением.

Соответствие требованию трёхуровневого доступа¶

Трёхуровневая модель доступа (аудитор — обычный пользователь — администратор) закрывается штатными ролями, без доработки:

Требование	Роль в Cryptex
Аудитор, только чтение	`viewer`
Обычный пользователь	`user`
Администратор	`admin`

Роль viewer предназначена именно для аудитора: она даёт доступ на просмотр и выгрузку и не допускает никаких изменений. Технически ограничение обеспечивается тем, что операции записи и удаления требуют роли user или admin, которых у viewer нет. Пользователю-аудитору достаточно членства в группе организации и роли viewer.

Настройка Keycloak¶

Чтобы токен содержал ожидаемые claim'ы, в realm нужно выполнить несколько шагов.

Realm roles. Создайте роли admin, user и viewer (Realm roles → Create role).
Группы = организации. Создайте группу на каждую компанию-арендатора (Groups → Create group). Имя группы станет идентификатором организации, по которому разделяются данные. Пользователей одной компании включайте в одну группу.
Group Membership mapper. Убедитесь, что в токене присутствует claim groups. В client scope клиента веб-интерфейса добавьте маппер Mappers → Add mapper → Group Membership: имя claim'а — groups. Признак «Full group path» можно оставить включённым — приложение само отрезает ведущий /.
Realm roles в токене. Маппер realm-ролей (realm_access.roles) в Keycloak включён по умолчанию; отдельно настраивать его обычно не требуется.
Назначение доступа. Каждому пользователю задайте членство в группе (организация) и назначьте одну из ролей: admin, user или viewer (для аудитора — viewer).

Проверка подлинности токена при развёртывании¶

Проверка токена вынесена на периметр и выполняется на уровне Ingress связкой OAuth2 Proxy + Keycloak. OAuth2 Proxy аутентифицирует пользователя в Keycloak и проверяет токен (подпись и срок действия) до того, как запрос попадёт в приложение. Таким образом backend всегда получает уже проверенный, подписанный и действующий JWT и ему достаточно прочитать из него claim'ы (groups, realm_access.roles) — повторно проверять подпись он не должен.

Из этого следует единственное эксплуатационное требование: API должен быть доступен только через этот Ingress. Прямой доступ к сервису в обход OAuth2 Proxy закрывается сетевыми средствами (Service типа ClusterIP, сетевые политики), чтобы к API нельзя было обратиться, минуя проверку токена.

Отдельно отметим режим разработки. Переменная DEV_MODE (по умолчанию false) полностью отключает аутентификацию: все запросы выполняются от фиксированной организации Cryptex-dev с ролью admin. Этот режим предназначен только для локальной разработки и демо-стендов. В промышленной установке DEV_MODE должен оставаться false.

Время жизни сессии¶

Cryptex не хранит серверных сессий и не имеет собственного параметра таймаута — временем жизни сессии целиком управляет Keycloak. Менять его нужно там же.

Realm-уровень¶

Realm settings → Sessions:

SSO Session Idle — время бездействия, после которого сессия завершается.
SSO Session Max — предельная длительность сессии независимо от активности.
Client Session Idle / Client Session Max — те же ограничения на уровне клиентской сессии, если нужно задать их отдельно.

Realm settings → Tokens:

Access Token Lifespan — срок жизни access-токена (обычно несколько минут).

Client-уровень¶

Параметры realm можно переопределить для конкретного клиента: Clients → (клиент веб-интерфейса) → Advanced → Advanced Settings — там задаются Access Token Lifespan и Client Session Idle/Max для этого клиента.

Как это работает на практике¶

Веб-интерфейс держит сессию на паре токенов: короткоживущем access-токене и refresh-токене. Access-токен периодически обновляется по refresh-токену. Когда истекает SSO Session (Idle или Max) либо refresh-токен, обновление становится невозможным и пользователь разлогинивается.

Отсюда практическое правило:

чтобы увеличить или сократить общую длительность сессии — меняйте SSO Session Idle (по простою) и SSO Session Max (жёсткий предел);
Access Token Lifespan влияет на частоту обновления токена, а не на общую длительность сессии.

Поскольку backend сам сессию не продлевает и не обрывает, любые изменения таймаута выполняются исключительно в Keycloak и вступают в силу для новых сессий.

Примечание

Пути в меню приведены для консоли администратора Keycloak на движке Quarkus. В старой консоли (Wildfly) те же параметры находятся в разделах Realm Settings → Tokens и Clients → (клиент) → Settings.