Управление и роли

Эта страница — про веб-интерфейс Alatyr (дальше — админка) и админский REST API: какие есть роли, кто что может делать и как устроены четыре потока, которые чаще всего вызывают вопросы — одобрение заявок, блокировка устройства, сервисные аккаунты и проверка источника заявки.

Про переменные окружения и развёртывание — Конфигурация и Установка.

Роли

Ролей ровно четыре. Назначает их cert-admin — в разделе Пользователи админки либо через PUT /api/v1/users/{email}/roles; локальным пользователям роль задаётся при создании (POST /api/v1/users/local).

Роль	Кому	Что может
cert-admin	человеку	Всё: одобрение и отклонение заявок, отзыв, блокировка и разблокировка устройств, пользователи и роли, сети, сервисные аккаунты, вебхуки, лицензия, все настройки.
cert-approver	человеку	Читать заявки, устройства, сертификаты, аудит, сети и метрики; одобрять заявки. Не может отклонять, отзывать и что-либо настраивать.
cert-viewer	человеку	То же чтение, что у cert-approver, без одобрения.
cert-auto-approver	только сервисному аккаунту, человеку эта роль не назначается	Наименьшие права: POST /requests/approve плюс чтение /requests и /requests/check-conflicts. Не видит аудит, устройства, сети и метрики — ровно то, что нужно, чтобы найти заявку и проверить конфликты перед одобрением.

Первый вошедший пользователь автоматически получает cert-admin — запись вставляется в пустую таблицу ролей атомарно, и это работает одинаково для Keycloak и для локального входа.

Установка только с Keycloak: закройте первый вход до того, как API станет доступен

Если API открыт наружу раньше, чем вы сами вошли первый раз, «первый вошедший» — это буквально первый обладатель действующего токена настроенного клиента Keycloak, а не обязательно вы.

Закрывайте это заранее, любым из трёх способов: войдите первым сами; либо настройте локального администратора (ALATYR_LOCAL_AUTH_ENABLED + ALATYR_LOCAL_ADMIN_EMAIL/ALATYR_LOCAL_ADMIN_PASSWORD, см. Конфигурация); либо заранее впишите нужную строку в таблицу ролей.

Что видно в админке каждой роли

Левое меню делится надвое. Первые пять разделов видят все админские роли, остальные показываются только cert-admin — не потому, что запись запрещена, а потому, что и чтение там ограничено.

Раздел меню	Кто видит	Кто может менять
Метрики	cert-admin, cert-approver, cert-viewer	—
Запросы	те же, плюс сервисный аккаунт (только список и проверка конфликтов)	одобрить — cert-admin, cert-approver, сервисный аккаунт; отклонить — только cert-admin
Сертификаты	те же три роли	отозвать — только cert-admin
Устройства	те же три роли; список SSH-ключей устройства и назначенные цели — тоже	отзыв и разблокировка устройства, назначение целей, смена enrollment-токена, запрос и удаление логов — только cert-admin
Аудит	те же три роли	— (аудит только читается)
Пользователи	cert-admin	cert-admin
802.1X сети	список сетей читают все три роли	cert-admin
Сервисные аккаунты	cert-admin (самим сервисным аккаунтам недоступно)	cert-admin
SSH-ключи	cert-admin	cert-admin
Разделяемые учётки	cert-admin	cert-admin
Запросы назначений	все три роли	решение по запросу — cert-admin
Выписанные задания	cert-admin	cert-admin
Кластеры Kubernetes	cert-admin	cert-admin
Вебхуки	cert-admin; раздел появляется, только если вебхуки включены (ALATYR_WEBHOOKS_ENABLED)	cert-admin
Лицензия	все три роли (состояние лицензии видно каждому)	активация, вывод из эксплуатации, перепривязка — cert-admin
Настройки	cert-admin	cert-admin

Чтение — не всегда «меньше», чем запись

Три справочника требуют cert-admin даже на чтение, и это решение, а не недосмотр:

• Настройки → Удостоверяющие центры и все настройки на вкладках «Политика выдачи» и «Безопасность по умолчанию» (GET /api/v1/settings/system, GET /api/v1/settings/issuers) — там же лежат разрешённые сети Keyholder, то есть ответ на вопрос «откуда меня вообще послушают»;
• SSH-ключи — общий список по всему парку (GET /api/v1/admin/ssh-keys) отдаёт все принципалы разом. Соседний список ключей одного устройства остаётся доступен остальным ролям намеренно: он отвечает про машину, которую читатель и так открыл;
• Разделяемые учётки и Проверка владения устройством (/api/v1/admin/principal-aliases, /api/v1/admin/corp-allowlist) — список говорит, кто может войти под общей учётной записью.

Остальные вкладки настроек читает любая админская роль, а пишет только cert-admin: «Аутентификация источника (enroll)» (GET /api/v1/settings/enroll-source-auth), «Проверка владения устройством» в части политики (GET /api/v1/settings/sa-auto-approve), «Обновление агента» (GET /api/v1/settings/agent-update/stuck), «Лицензия» (GET /api/v1/license/status).

Одобрение, отклонение и отзыв

Заявки на выпуск создаются только через эндпоинты регистрации (/enroll, /enroll/user, /enroll/ssh) по enrollment_token устройства и всегда попадают в состояние ожидания. Ни одна цель — wifi, user_mtls, ad_logon, ssh, k8s, vpn — не выдаётся автоматически по самому факту регистрации: нужно решение человека или сервисного аккаунта.

Действие	Эндпоинт	Кто может
Одобрить (пачкой)	POST /api/v1/requests/approve	cert-admin, cert-approver, сервисный аккаунт с ролью cert-auto-approver
Отклонить (пачкой)	POST /api/v1/requests/reject	только cert-admin
Отозвать сертификат	POST /api/v1/certificates/{serial}/revoke	только cert-admin

Одобрение человеком и одобрение сервисным аккаунтом — разные вещи. Когда одобряет человек, дополнительных проверок нет: разрешено всё, кроме заявок в терминальном состоянии. Когда одобряет сервисный аккаунт, заявка сначала проходит независимую последовательность проверок: аппаратная аттестация, соответствие цели списку разрешённых для этого токена, проверка владения устройством (если включена) и блокировка устройства.

Отзыв сертификата, выпущенного через SCEP, невозможен

У протокола SCEP нет операции отзыва. Кнопка в админке отключена, API вернёт 400. Отзывайте такой сертификат на стороне вашего CA напрямую.

Проверка владения устройством (вкладка Настройки → Проверка владения устройством, GET/PUT /api/v1/settings/sa-auto-approve) — отдельный сигнал, не зависящий от аппаратной аттестации:

Значение	Что проверяется
off (по умолчанию)	ничего
allowlist	серийный номер должен быть в списке разрешённых (CRUD — cert-admin, /api/v1/admin/corp-allowlist)
webhook	запрос в вашу систему учёта или MDM; запрос защищён от SSRF
allowlist_or_webhook / allowlist_and_webhook	комбинации двух предыдущих

Отсутствие настройки и ошибка проверки никогда не трактуются как разрешение: обе проверки отказывают в пользу отказа.

Сервисные аккаунты

Машинные учётные записи для одобрения через API (CI, автоматизация) вместо интерактивного входа. Управление — только cert-admin, и самим сервисным аккаунтам недоступно: иначе один токен мог бы создать себе второй с большими правами.

Метод и путь	Назначение
GET /api/v1/service-accounts	Список
POST /api/v1/service-accounts	Создать. Токен вида wca_* показывается один раз в ответе
PUT /api/v1/service-accounts/{id}/enabled	Включить или выключить
PUT /api/v1/service-accounts/{id}/allowed-purposes	Изменить список целей, которые этот токен вправе одобрять
DELETE /api/v1/service-accounts/{id}	Удалить

Что важно знать:

• Права токена ограничены списком целей. Он задаётся при создании и правится отдельно; пустым быть не может. У токенов, заведённых до появления этой настройки, в списке ровно wifi — то есть права могут только расшириться, и только там, где администратор явно поставил галочку. Расширение за пределы wifi — настоящий размен, а не удобство: user_mtls, ad_logon, ssh, k8s и vpn утверждают личность человека.
• В базе хранится только SHA-256-хеш токена; открытое значение существует единственный раз — в ответе на создание.
• Токен с префиксом wca_ распознаётся до проверки JWT. Неизвестный, выключенный или истёкший токен, а также ошибка базы — 401.
• Срок действия задаётся при создании (expires_in_days, от 0 до 3650; 0 или пусто — бессрочный).
• Аудит различает действия человека и действия токена; в админке на записях сервисного аккаунта стоит метка «API».
• Единственное изменяющее действие, доступное токену, — одобрение заявки. Отклонение, отзыв, управление пользователями и сетями остаются за cert-admin независимо от токена.

Блокировка устройства при отзыве

POST /api/v1/devices/{serial}/revoke (cert-admin) отзывает все действующие сертификаты устройства и — только если отозвались все до одного — дополнительно ставит на устройство постоянную блокировку с записью в аудит. Частичный сбой отзыва (ответ 207) блокировку не ставит: та же проверка уже защищает освобождение места лицензии (см. Лицензирование).

• POST /api/v1/devices/{serial}/unblock (cert-admin) — единственный способ снять блокировку: явное обратимое действие человека. Повторный вызов на уже разблокированном устройстве — успех, не ошибка. Разблокировка не трогает ожидающие заявки.
• Пока устройство заблокировано, все три эндпоинта регистрации по-прежнему создают обычную заявку — никогда не 403 — но помечают её признаком «зарегистрировано во время блокировки». Признак постоянный: последующая разблокировка его не снимает, это историческая запись про конкретную заявку.
• Сервисный аккаунт отклоняет такую заявку безусловно — и по этому признаку, и если устройство заблокировано в момент проверки. Оба сигнала проверяются независимо: иначе заявка, оставшаяся в очереди к моменту блокировки (а потому не помеченная задним числом), прошла бы автоодобрение.
• Человек может одобрить такую заявку вручную в любой момент. Блокировку устройства это не снимает — для неё нужна отдельная явная разблокировка.

Что блокировка не останавливает

Блокировка привязана к строке устройства, которая определяется по серийному номеру, заявленному самим агентом. Устройство, физически контролирующее свой агент (а это ровно та угроза, против которой механизм и сделан), может обойти блокировку: заявить другой серийный номер — появится новая, незаблокированная строка, — либо, для подставных серийников, просто не предъявить continuity_key при повторной регистрации.

Это не новая брешь: то же самое давно верно для отзыва сертификата на уровне устройства. Блокировка также не останавливает уже выданные SSH-ключи из реестра — см. Реестр ключей и Keyholder API.

Для парка с TPM обход закрывается включением TPM_REJECT_UNATTESTED и TPM_REQUIRE_AK_CERTIFY (Конфигурация): заявленный серийный номер тогда обязан совпасть с аттестованным железом.

Аутентификация источника заявки

Эндпоинты регистрации (/enroll, /enroll/user, /enroll/ssh) принципиально не требуют авторизации — у агента ещё нет токена при первом обращении к серверу. Без дополнительной проверки это значит, что запрос от произвольного HTTP-клиента с правильно оформленным телом тоже встанет в очередь, неотличимо от заявки настоящего агента: сама по себе аттестация носит рекомендательный характер и создание заявки не блокирует.

Аутентификация источника закрывает этот разрыв. Агент подписывает тело заявки тем же аппаратным ключом, которым построен CSR (TPM AK на Windows и Linux, ключ Secure Enclave на macOS), а сервер проверяет подпись против открытого ключа из самого CSR — до того, как заявка вообще появится в очереди.

Режим общий на весь парк, четыре ступени, каждая строже предыдущей:

Ступень	Поведение
off (по умолчанию)	Поведение не меняется; результат проверки только записывается.
version_floor	Отклоняет (403) агентов ниже заданной версии. Это инструмент миграции — сначала перевести парк на сборки, умеющие подписывать заявку, — а не самостоятельная защита.
attestation_hardgate	Требует аппаратную подпись заявки; при отсутствующей или неверной подписи заявка отклоняется (403) до создания записи.
strict	То же плюс синхронная проверка полной цепочки аттестации для Windows и Linux. Для macOS цепочка не проверяется — Secure Enclave не даёт внешне проверяемой цепочки EK, поэтому там принимается сама подпись. Программный (не аппаратный) ключ отклоняется на любой платформе.

Отклонение на любой включённой ступени возвращает одну и ту же ошибку 403 enroll_source_auth_failed: по коду нельзя определить, что именно не совпало — версия, подпись или цепочка.

Порядок включения. Функция рассчитана на поэтапный запуск: off → version_floor (вытеснить старые агенты) → attestation_hardgate → и только после стабилизации strict. Переходить сразу к strict не стоит.

Где менять. Вкладка Настройки → Аутентификация источника (enroll) либо GET/PUT /api/v1/settings/enroll-source-auth (чтение — любая админская роль, запись — только cert-admin). Каждое изменение попадает в аудит с указанием, кто и когда его сделал и какими были значения до и после.

Что эта подпись доказывает, а что нет

Сервер проверяет подпись против открытого ключа, взятого из самого присланного CSR. Это доказывает, что заявку подписал владелец ключа, которым построен этот CSR, — то есть связывает тело заявки с ключом и закрывает две конкретные атаки: переклейку чужой аттестации на свою заявку и повтор ранее перехваченной заявки.

Аутентификацией устройства эта подпись не является. На вопрос «а тот ли это ключ, которого мы ждём от этой машины» она не отвечает: отправитель, сгенерировавший собственную пару ключей и собственный CSR, подпишет заявку тем же ключом и проверку пройдёт.

Отвечает на этот вопрос аппаратная аттестация:

• Windows и Linux — TPM2_Certify привязывает ключ CSR к TPM, чей EK-сертификат подписан производителем. Здесь ступени attestation_hardgate и strict действительно поднимают планку до «ключ живёт в проверяемом аппаратном модуле».
• macOS — такой привязки не существует до macOS 27, см. Известные ограничения. Поэтому на macOS барьером остаётся ручное одобрение заявки, а не подпись.

Как снизить риск подделанной заявки сейчас

Пока App Attest недоступен на вашем парке маков, риск закрывается организационно и сетевым контуром. По убыванию эффективности:

1. Не выставляйте эндпоинты регистрации в интернет. Они не требуют авторизации по устройству протокола, поэтому доступность снаружи — риск сама по себе. Ограничьте доступ корпоративной сетью или VPN. Это единственная мера, которая полностью снимает сценарий «заявку прислали произвольным клиентом извне», и она не требует изменений в агентах.
2. Не включайте автоодобрение для macOS. Сервисный аккаунт и так не может одобрить заявку с ключом Secure Enclave, пока не настроена проверка владения устройством. Это поведение по умолчанию, и ослаблять его не стоит.
3. Настройте проверку владения устройством. Список разрешённых серийных номеров помогает только против выдуманных серийников; против настоящего серийника из вашего парка работает вариант webhook — запрос в вашу систему учёта или MDM с вопросом, действительно ли эта машина сейчас управляется и на связи.
4. Проверяйте при одобрении, что заявка ожидаема. Полезные признаки в очереди: у устройства уже есть действующий сертификат, а пришла новая заявка; заявка пришла с машины, которой не должно быть в работе; несколько заявок на один серийный номер подряд. Каждое решение попадает в аудит с указанием, кто его принял.
5. Включите TPM_REJECT_SOFTWARE для парка, где аппаратный ключ обязателен: это отсекает заявки вообще без TPM и Secure Enclave, хотя и не отличает подлинный Secure Enclave от заявленного.

Для Windows и Linux дополнительно доступны ступени attestation_hardgate и strict — там они дают настоящую аппаратную гарантию, а не только связывание тела заявки с ключом.

Пользователи и роли

PUT /api/v1/users/{email}/roles и PUT /api/v1/users/{email}/enabled (cert-admin) управляют ролями и активностью учётной записи. Локальные пользователи заводятся и обслуживаются отдельными эндпоинтами (POST /api/v1/users/local, PUT /api/v1/users/{email}/password); подробности локального входа и первого администратора — в разделе про локальную аутентификацию на странице Конфигурация.

Цели и сети

Что именно Alatyr выдаёт на устройство, называется целью. Назначает цели устройству cert-admin (Устройства → строка машины), а устройство может их запрашивать само — такие запросы собираются в разделе Запросы назначений. Как настроить каждую цель:

Цель	Что даёт	Читайте
wifi	Wi-Fi и проводной 802.1X	Настройка сети
user_mtls	вход сотрудника во внутренние приложения по сертификату	mTLS пользователя
ssh	вход по SSH без файлов с ключами	Настройка SSH-доступа
ad_logon	вход в домен и по RDP по смарт-карте	Вход в домен по смарт-карте
k8s	доступ к Kubernetes через kubectl	Доступ к Kubernetes
vpn	клиентский сертификат для OpenVPN	Приёмники

Список сетей 802.1X читают все три админские роли; создаёт, отключает, восстанавливает и удаляет записи только cert-admin. Он же задаёт имя RADIUS-сервера (Имя RADIUS-сервера) и переключает распространение профиля через агента (Кто ставит профиль).