Как выбрать настройки Zentro: подпись, адреса, секреты, приложения

Для администратора, который ставит Zentro впервые и не обязан разбираться в OAuth и криптографии. Здесь — что выбрать и почему, с готовыми рецептами. Где вписывать значения — Единый вход (переменные Identity), Установка панели и кабинета (фронт), Настройки установки (настройки в панели), Подключение приложения (приложения).

Размер сервера — Требования к серверу.

Сначала — что потом не поменять

Большинство настроек можно крутить в любой момент. Но несколько решений принимаются один раз при установке — их смена болезненна. На них стоит потратить десять минут.

Решение	Что будет при смене	Подробно
Адрес Identity (PUBLIC_BASE_URL)	перенастраивать все подключённые приложения	«Адреса»
Домен ключей (WEBAUTHN_RP_ID)	все ключи (passkey) пользователей перестают работать, заводить заново	«Адреса»
Шифрование логинов и почты в базе (security.pii_encryption_at_rest)	включить можно, выключить — нет	«Настройки в панели»
Где хранятся ключи (SECRETS_BACKEND)	переезд ключей — работа специалиста; потеря ключей = потеря данных	«Секреты»
Тип subject и публичность у приложения	только пересоздать приложение	«Приложения»

Алгоритм подписи и хеш секретов приложений меняются без простоя из панели — их можно оставить по умолчанию и вернуться к ним, когда понадобится.

Готовые рецепты

Не уверены — берите рецепт своего профиля целиком.

Настройка	Личный / пилот	Малая организация	Средняя и больше
SIGNING_ALG	RS256 (по умолчанию)	RS256	RS256; ES256 — если все приложения свои и современные
security.client_secret_hash	sha256 (по умолчанию)	sha256	sha256; argon2id — только по требованию регламента
SECRETS_BACKEND	local (+ ALLOW_LOCAL_SECRETS=true)	vault	vault (кластер)
CACHE_BACKEND	memory	memory	redis (с двух серверов приложений)
DB_SSLMODE	disable (база на том же сервере)	disable на том же сервере, require — на другом	require
SMTP_TLS	как у почтового провайдера	starttls (порт 587)	starttls
AUDIT_RETENTION	2160h (90 дней)	8760h (1 год)	по требованиям регулятора
security.self_registration_enabled	выкл.	вкл., если есть внешние клиенты (магазин); иначе выкл.	выкл. для сотрудников
security.pii_encryption_at_rest	выкл.	вкл., если в базе клиенты-физлица	вкл.
security.admin_min_aal / privileged_min_aal	AAL2 / AAL2	AAL2 / AAL2	AAL2 / AAL3 (опасное — только ключом)

Подпись токенов

Что это

Zentro выдаёт приложениям токены — «пропуска», подписанные Zentro. Приложение проверяет подпись и верит пропуску. Алгоритм подписи — «на каком языке» расписывается Zentro. Если приложение этот язык не понимает, оно отвергнет пропуск, и вход не получится.

Варианты

Алгоритм	Кто понимает	Плюсы	Минусы
RS256 (по умолчанию)	все: обязателен по стандарту OIDC	максимальная совместимость: коробочные продукты, оборудование (NAS, роутеры), облачные сервисы, старые библиотеки	токен чуть длиннее (~300 байт) — на практике незаметно
ES256	современные библиотеки и сервисы	компактнее, подпись быстрее	часть коробочных продуктов и оборудования его не понимает
EdDSA	только самые новые библиотеки	самый современный	многие приложения не понимают — только по требованию продукта или регламента

ES256 не безопаснее RS256 в практическом смысле — оба надёжны. Выбор — только про совместимость.

Как выбрать

Оставьте RS256. Его понимают все, и он стоит по умолчанию — при установке ничего делать не нужно (SIGNING_ALG в .env Identity можно не трогать).

ES256 для всей системы имеет смысл, только если все приложения — ваши собственные сервисы на современных библиотеках и коробочных продуктов не будет.

Одно приложение понимает другой алгоритм — не меняйте алгоритм для всех. Задайте его только этому приложению: OAuth-клиенты → приложение → Алгоритм подписи (для бэкендов — то же поле у ресурса). Zentro сам заведёт ключ нужного алгоритма; через пару минут приложение начнёт получать токены, подписанные им, остальные приложения ничего не заметят. Пусто — алгоритм по умолчанию; подсказка у поля: задавайте, только если продукт не понимает алгоритм по умолчанию.

Как узнать, что понимает приложение

В документации приложения ищите слова «signing algorithm», «RS256», «ES256», «JWKS». Если указан только RS256 или ничего не указано — считайте, что RS256. Признак несовместимости после подключения: вход в Zentro проходит, а приложение пишет «invalid signature», «unsupported algorithm», «token validation failed».

Как поменять потом

Настройки → Безопасность → Ключи подписи. Там видно, какой алгоритм по умолчанию, какие ключи действуют и сколько приложений на каком алгоритме. Смена — мастером в два шага:

1. Проверка — Zentro ничего не меняет, а показывает план: когда новый ключ начнёт подписывать, какой заменит, сколько приложений затронет, и предупреждения.
2. Подтверждение — новый ключ публикуется сразу, а подписывать начинает через 24 часа (оставьте этот срок): приложения успеют узнать новый ключ заранее, и никто не получит «чужой» токен. Старые токены продолжают проверяться до конца своего срока.

Простоя нет, пользователей не разлогинивает: сессии и секреты приложений от подписи не зависят.

Плановая смена ключа (тот же алгоритм) — раз в год или сразу при подозрении, что ключ украден.

Отменить запланированную смену — «Вывести» ключ со статусом «Начнёт подписывать».

Проверка пишет про права бэкенда ключей — у Identity нет права создавать ключи. С Vault — политике Identity нужны права create/update на transit/keys/identity-signing-* (в комплекте Identity они есть; проверьте, если политику писали сами). Без Vault — каталог ключей должен быть доступен на запись.

Хеш секретов приложений

У приложений с сервером есть секрет (client_secret). Zentro хранит не сам секрет, а его отпечаток (хеш) и сверяет с ним секрет при каждом обращении приложения.

Вариант	Когда	Цена
sha256 (по умолчанию)	всегда, если регламент не требует иного	проверка — микросекунды
argon2id	регламент требует «медленный хеш для любых секретов»	~0.1 с процессора и 64 МБ памяти на каждое обращение приложения — сервер нужен больше (Требования к серверу)

Почему sha256 безопасно: секрет придумывает не человек, а Zentro — 256 случайных бит. Подобрать его нельзя ни перебором, ни по украденному отпечатку. Медленный хеш нужен паролям людей (их подбирают по словарю) — пароли пользователей всегда хранятся в argon2id, эта настройка их не касается.

Где менять: вся система — Настройки → Безопасность (security.client_secret_hash); сервис или отдельное приложение может переопределить («как у всех» — значение уровнем выше). Если регламент требует argon2id — для нагруженных машинных клиентов (сервис-сервис, интроспекция) всё равно лучше оставить sha256 на уровне клиента и согласовать это исключение.

Смена применяется сама: при следующем обращении приложения Zentro пересчитает отпечаток. Секрет менять не нужно, приложению делать ничего не надо.

Адреса

Что	Рекомендация	Почему
PUBLIC_BASE_URL	https://id.<ваш-домен> — отдельное постоянное имя	Это «имя» Zentro в каждом токене. Сменили — перенастраивать все приложения. Не используйте временные имена, IP, адреса облачного провайдера
Кабинет	https://account.<ваш-домен>	Открыт всем, кто входит
Панель	https://admin.<ваш-домен>	Только внутренняя сеть или VPN
WEBAUTHN_RP_ID	<ваш-домен> — общий родитель трёх адресов выше	Ключи (passkey) привязаны к этому домену навсегда. Сменили — пользователи заводят ключи заново

Правило: все три адреса — поддомены одного домена, которым вы владеете и который не собираетесь менять. Купить домен под Zentro дешевле, чем потом переезжать.

Секреты (SECRETS_BACKEND)

Zentro хранит ключи подписи и ключи шифрования персональных данных.

Вариант	Когда	Цена
vault	заказчик с персональными данными клиентов или сотрудников; есть кому сопровождать Vault	ещё один сервис: обновлять, бэкапить, хранить ключи распечатки вне сервера
local	личный стенд, пилот, тест	ключи лежат файлом на диске сервера: кто получил диск — получил ключи

Как настроить local — Установка сервера.

В обоих случаях: без бэкапа ключей бэкап базы бесполезен — данные не расшифровать (Требования к серверу, «Диск и бэкапы»).

Кэш и база

• CACHE_BACKEND: memory, пока Identity — один экземпляр. redis — обязательно, как только экземпляров два и больше: иначе отзыв токенов и лимиты на одном экземпляре не видны другому.
• DB_SSLMODE: disable — только если база на том же сервере и в закрытой сети Docker. База на другом сервере — require.

Почта

Без почты не работают регистрация, подтверждение адреса и сброс пароля.

• Берите почтового провайдера (транзакционная почта) или корпоративный почтовый сервер.
• Настройте у домена отправителя SPF, DKIM и DMARC (делается у провайдера домена) — иначе письма уходят в спам.
• SMTP_TLS: порт 587 — starttls, порт 465 — tls. none — никогда, кроме теста.

Аудит и приватность

Настройка	По умолчанию	Как выбрать
AUDIT_RETENTION	8760h (1 год)	Сколько хранить журнал. Больше — больше диска (~15–20 ГБ в год для малой организации). Спросите юриста, сколько требует закон или договор
PRIVACY_ERASURE_CRYPTO_SHRED_AFTER	720h (30 дней)	Через сколько после запроса на удаление данные человека становятся нечитаемыми. Оставьте
PRIVACY_ERASURE_HARD_DELETE_AFTER	8760h (1 год)	Через сколько запись удаляется физически. Оставьте, если юрист не сказал иначе

Настройки в панели

Меняются в любой момент (Настройки, подробно — Настройки установки). Рекомендации:

Настройка	Рекомендация
Второй фактор для панели (admin_min_aal)	AAL2 — всегда. Без второго фактора в панель не войти, это нормально
Опасные операции (privileged_min_aal)	AAL2; AAL3 (только ключом), когда у всех администраторов есть ключи
Самостоятельная регистрация	вкл. — только если в Zentro входят внешние клиенты (покупатели). Для сотрудников — выкл., учётки заводит администратор
Шифрование логинов и почты	решите при установке: включить можно позже, выключить нельзя. Есть физлица-клиенты — включайте
Длина пароля	12 по умолчанию — оставьте
Доверенное устройство	30 дней по умолчанию; для администраторов на чужих компьютерах — меньше

Приложения

Можно ли подключить приложение — проверка до начала

Найдите в документации приложения раздел про SSO / OIDC / «единый вход» и ответьте на вопросы:

Вопрос	Нужный ответ	Если нет
Поддерживает OpenID Connect (OIDC)?	да	только SAML или ничего — подключить напрямую нельзя, есть шлюз (Шлюз для приложений без SSO)
Умеет PKCE (code_challenge, S256)?	да	сейчас не подключить: Zentro требует PKCE от всех приложений. Шлюз или вопрос к поставщику Zentro
Какой алгоритм подписи понимает?	RS256 (по умолчанию)	задать приложению свой — раздел «Подпись токенов»
Откуда берёт имя пользователя?	из userinfo или настраиваемого claim	если только из id_token — имя придётся сопоставлять по sub (идентификатор Zentro): Zentro кладёт логин и почту в userinfo, а не в id_token
Сам заводит пользователей при первом входе?	да	учётки в приложении заводить заранее с теми же логинами
Как будет входить администратор, если Zentro недоступен?	есть локальный вход	не отключайте локального администратора приложения

Если все ответы «да» — подключайте по Подключение приложения. Если хоть один «нет» — сначала попробуйте на тестовом стенде.

Поля приложения — что выбрать

Поле	Рекомендация
Кто будет входить	«Люди» — сайт, панель, оборудование; «Сервис» — программа без пользователя
Публичный клиент	нет — почти всегда. «Да» — только приложение целиком в браузере или мобильное, у которого нет своего сервера. Потом не меняется
Scopes	openid profile email — обычно. Не давайте лишнего
Приложение организации (без согласия)	да — для своих приложений и оборудования. Для чужих — нет: пусть пользователь видит, кому отдаёт данные
Тип subject	public — для своих приложений (один идентификатор человека везде). pairwise — для сторонних, чтобы они не могли сопоставлять людей между собой. Потом не меняется
Пространство прав	задавайте, если приложение должно знать права пользователя (или пускать по роли)
Back-channel logout	если приложение умеет — включайте: выход из Zentro завершит сессию и в приложении
Алгоритм подписи	пусто (по умолчанию). Задавайте, только если приложение не понимает алгоритм по умолчанию
Хеш секрета	«как у всех». Не трогайте без причины

Пример: сетевое хранилище со встроенным OIDC

Хранилище «Склад-NAS» (выдумано) умеет OIDC, понимает только RS256, имя пользователя берёт из настраиваемого claim, учётки не заводит.

1. Проверка: OIDC — да; PKCE — проверить на тесте; RS256 — по умолчанию, ничего не делать; claim — preferred_username; учётки — завести в хранилище заранее с логинами как в Zentro.
2. Приложение в Zentro: «Люди», не публичный, openid profile email, «Приложение организации» — да, public, Redirect URI — тот, что показывает хранилище.
3. В хранилище: адрес Discovery https://id.example.com/.well-known/openid-configuration, client_id, секрет, claim preferred_username. Локального администратора хранилища не трогать.
4. Тест в режиме инкогнито. Ошибка про PKCE на экране Zentro — хранилище PKCE не умеет; ошибка подписи в хранилище — задать приложению «Алгоритм подписи» RS256, если по умолчанию сменили; «пользователь не найден» — нет учётки или не тот claim.