</details>

<details>
<summary><strong>Пользовательская пара SSH-ключей</strong></summary>

По умолчанию Bastillion генерирует собственную пару ключей Ed25519 при первом запуске. Чтобы использовать свою собственную,
проще всего сделать это через интерфейс: **Настройки → Заменить SSH-ключ приложения**
(только для учётных записей администратора) — вставьте закрытый ключ, открытый ключ и парольную фразу, если она есть,
и изменения вступят в силу немедленно, без перезапуска.

⚠️ Это заменяет *единственный* ключ, которому доверяет каждая зарегистрированная система. Это предназначено как одноразовый шаг
при первоначальной настройке Bastillion, **до** регистрации каких-либо систем — если у вас
уже зарегистрированы системы, Bastillion потеряет SSH-доступ ко всем ним в тот момент, когда вы замените
ключ, если только этот точный ключ уже не находится в `authorized_keys` на каждой из них
заранее. Страница настроек требует дополнительный флажок подтверждения, как только у вас есть
зарегистрированные системы, именно из-за этого.

**Уже есть зарегистрированные системы, и всё равно нужно ротировать ключ?** Предварительно разместите новый ключ
через сам Bastillion, а не редактируйте `authorized_keys` вручную повсюду:

1. Установите `FORCE_USER_KEY_GENERATION=false`, чтобы **Управление SSH-ключами → Добавить SSH-ключ** позволяло вставить
   существующий открытый ключ вместо только генерации нового.
2. Добавьте там новый ключ для профиля, охватывающего все ваши системы, и подтвердите (в разделе
   «Управление SSH-ключами» или в статусе каждой системы), что он действительно размещён везде — учитывайте
   `AUTH_KEYS_REFRESH_INTERVAL`, поскольку именно он отвечает за распространение.
3. Только когда вы уверены, что ключ есть на каждой системе, замените ключ приложения в настройках.
4. Верните `FORCE_USER_KEY_GENERATION` к предыдущему значению, затем, после подтверждения,
   что новый ключ приложения распространился на все системы (снова учитывайте
   `AUTH_KEYS_REFRESH_INTERVAL`), удалите ключ, добавленный на шаге 2, из раздела «Управление SSH-ключами» —
   он был размещён там только для предварительного заполнения `authorized_keys` и в дальнейшем не нужен.

Для сценарных/безголовых установок то же самое можно сделать через переменные окружения и
перезапуск вместо этого:```bash
# Regenerate and import SSH keys
export RESET_APPLICATION_SSH_KEY=true

# Private key
export PRIVATE_KEY=/Users/you/.ssh/id_rsa

# Public key
export PUBLIC_KEY=/Users/you/.ssh/id_rsa.pub

# Passphrase (leave blank if none)
export DEFAULT_SSH_PASSPHRASE=myPa$$w0rd

</details>

<details>
<summary><strong>Настройки базы данных</strong></summary>

Пример встроенной H2:```bash
export DB_USER=bastillion
export DB_PASSWORD=p@$$w0rd!!
export DB_DRIVER=org.h2.Driver
export DB_CONNECTION_URL=jdbc:h2:file:keydb/bastillion;CIPHER=AES;

</details>

<details>
<summary><strong>Внешняя аутентификация (LDAP / JAAS)</strong></summary>

Аутентификация через существующий сервер LDAP/Active Directory вместо локальных
паролей (или наряду с ними). Включите её:```bash
export JAAS_MODULE=ldap-ol

Чтобы сопоставить роли LDAP с профилями Bastillion:```
ldap-ol-with-roles {
    org.eclipse.jetty.security.jaas.spi.LdapLoginModule required
    debug="false"
    useLdaps="false"
    contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
    hostname="<SERVER>"
    port="389"
    bindDn="<BIND-DN>"
    bindPassword="<BIND-DN PASSWORD>"
    authenticationMethod="simple"
    forceBindingLogin="true"
    userBaseDn="ou=users,dc=bastillion,dc=com"
    userRdnAttribute="uid"
    userIdAttribute="uid"
    userPasswordAttribute="userPassword"
    userObjectClass="inetOrgPerson"
    roleBaseDn="ou=groups,dc=bastillion,dc=com"
    roleNameAttribute="cn"
    roleMemberAttribute="member"
    roleObjectClass="groupOfNames";
};

</details>

<details>
<summary><strong>Единый вход (SAML 2.0)</strong></summary>

Аутентификация через корпоративный поставщик удостоверений — Microsoft Entra ID, Okta, ADFS или любой
SAML 2.0 IdP — вместо локальных паролей или LDAP (или наряду с ними). После настройки на странице входа появляется кнопка **Войти через SSO**. Включите её:```bash
export SAML_BASE_URL=https://bastillion.example.com
export SAML_IDP_METADATA_URL=https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>

Только если Entity ID, зарегистрированный на стороне IdP, не может точно совпадать с `SAML_BASE_URL`:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

Администраторы добавляются при первом входе через SSO и могут получать системные профили.

**Имя пользователя, отображаемое в Bastillion:** SAML NameID становится именем пользователя. Entra по умолчанию отправляет
`user.userprincipalname`, что подходит для обычных участников тенанта, но создаёт
некрасивый гостевой UPN вида `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com` для B2B-гостей (любых,
вошедших с личной или внешней почтой, добавленных как гости). Чтобы получить более чистое имя пользователя, перейдите в
*Single sign-on* корпоративного приложения → SAML → *Attributes & Claims*, отредактируйте **Unique
User Identifier (Name ID)** и измените его *Source attribute* с `user.userprincipalname`
на `user.mail`.

**Как на самом деле работает сопоставление ролей — тот же механизм, что и для LDAP выше:** `SAML_ROLE_ATTRIBUTE`
указывает, *какой* атрибут утверждения содержит группы/роли пользователя; *значения*, которые
этот атрибут содержит при конкретном входе, сравниваются **по точному текстовому совпадению** с именами
профилей, созданных вами в разделе **Manage → Profiles**. Значение, совпадающее с именем профиля,
назначает пользователя этому профилю; больше ничего в утверждении не имеет значения. Таким образом, профиль Bastillion должен называться
точно так же, как строка, которую отправляет утверждение — отдельного шага сопоставления
или интерфейса нет, имена просто должны совпадать.

Именно эта часть чаще всего вызывает проблемы у людей именно с Entra ID: по умолчанию
утверждение групп Entra может отправлять каждую группу как её **Object ID** (GUID), а не как отображаемое
имя, если конфигурация токена корпоративного приложения явно не настроена на отправку **имён** групп.
Если ваши профили Bastillion названы, например, `admins`/`everyone`, но Entra
отправляет GUID, ничего никогда не совпадёт. Проверьте фактическое значение утверждения в реальном запросе (или
конфигурацию токена Entra для приложения), прежде чем предполагать, что сопоставление сломано — обычно проблема
именно в этом, а не на стороне Bastillion. Три способа исправить это, в порядке наших рекомендаций:

1. **Используйте App Roles Entra вместо утверждений групп (самый чистый способ).** В регистрации приложения →
   App roles определите роли с точно теми значениями, которые вам нужны (`admins`, `everyone`, ...), затем
   назначьте пользователей/группы на эти роли в разделе *Users and groups* корпоративного приложения.
   Настройте SAML-токен на отправку утверждения `roles` и укажите `SAML_ROLE_ATTRIBUTE` на
   URI этого утверждения вместо утверждения групп. Вы выбираете точную строку, которую отправляет Entra — никакой проблемы
   с GUID вообще, и это более чистая модель авторизации, чем повторное использование AD-групп.
2. **Измените исходный атрибут утверждения групп.** Enterprise Application → Single sign-on →
   SAML → *Attributes & Claims* → отредактируйте утверждение Groups → там есть раскрывающийся список
   *Source attribute*, обычно по умолчанию установлен Group ID. В зависимости от вашего тенанта и того, являются ли группы
   облачными или синхронизированными из локального AD, вы можете переключить его на `sAMAccountName`
   или вариант отображаемого имени — точные варианты зависят от тенанта и версии портала Entra, поэтому проверяйте,
   что реально предлагается, а не предполагайте конкретную метку.
3. **Или не боритесь с этим — назовите профиль Bastillion в соответствии с тем, что Entra реально отправляет.** Если
   Entra настаивает на отправке GUID, создайте профиль Bastillion, буквально названный этим GUID.
   Менее красиво, но не требует перенастройки на стороне Entra.

Пользователь, чьи утверждения не совпадают ни с одним профилем Bastillion, отклоняется при входе (аккаунты **Manager** —
единственное исключение; они не привязаны к профилям) — точно так же, как с LDAP, поэтому
`DEFAULT_PROFILE_FOR_SAML` выше стоит задать по той же причине, по которой задаётся
`DEFAULT_PROFILE_FOR_LDAP`: как страховочная сетка, пока вы ещё выравниваете имена профилей с
значениями утверждений вашего IdP.

Собственная проверка одноразового пароля Bastillion пропускается для SSO-входов — ожидается, что IdP
обеспечивает собственную политику MFA/Conditional Access. Первичная регистрация OTP по-прежнему
предлагается, чтобы у SAML-пользователей был локальный резервный идентификатор на случай отключения SSO.

**Подписанные запросы и зашифрованные утверждения:** Bastillion автоматически генерирует собственный сертификат подписи SAML
(самоподписанный, так же, как генерирует свой TLS-сертификат) при
первой необходимости и с тех пор подписывает им каждый исходящий AuthnRequest — никакой
настройки не требуется, и это безвредно, даже если ваш IdP его не проверяет. Получите
`https://bastillion.example.com/saml/metadata`, чтобы получить этот сертификат в стандартной форме
SP-метаданных, и передайте его администратору IdP, если они должны проверять подписанные
запросы Bastillion или шифровать утверждения для Bastillion — большинство IdP могут импортировать URL
SP-метаданных напрямую вместо вставки сырого сертификата. Если вы предпочитаете использовать настоящую (например,
выпущенную CA) пару ключей вместо автоматически сгенерированной, укажите `SAML_SP_KEYSTORE_PATH`/
`SAML_SP_KEYSTORE_PASSWORD` на хранилище ключей PKCS12, содержащее её. Чтобы *требовать* зашифрованные
утверждения (по умолчанию выключено — включайте это только после того, как ваш IdP действительно настроен
шифровать для сертификата Bastillion, иначе каждый вход начнёт завершаться ошибкой):```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

Также существует файловый журнал аудита, отключённый по умолчанию. Включите его в **log4j2.xml**, раскомментировав:
- `io.bastillion.manage.util.SystemAudit`
- `audit-appender`

> https://github.com/bastillion-io/Bastillion/blob/main/src/main/resources/log4j2.xml#L19-L22
</details>

<details>
<summary><strong>Миграция с v4</strong></summary>

Обновляетесь со старой установки Bastillion v4 и хотите сохранить своих пользователей, системы, профили,
скрипты и (что самое важное) существующую SSH-ключевую пару приложения, вместо того чтобы начинать
заново? `tools/migrate/` содержит автономный инструмент миграции именно для этого — он экспортирует каждую
таблицу из старой базы данных H2 (расшифровывая столбцы, зашифрованные на уровне приложения, с помощью
хранилища ключей СТАРОГО экземпляра) в JSON-файл, а затем импортирует его в новый экземпляр v5 (повторно
шифруя с помощью хранилища ключей НОВОГО экземпляра). Существующие пользователи могут войти в систему со своими текущими паролями
сразу после этого — без принудительного сброса.```bash
cd tools/migrate

# 1. Export the old database
./migrate.sh export /opt/Bastillion-jetty/jetty/bastillion/WEB-INF/classes/ ~/bastillion-export.json

# 2. Start the new v5 instance once against the config dir you're migrating into, then
#    stop it (Ctrl+C) once it's finished booting - this creates the schema, jceks, and
#    default admin user.
cd ../..
java -DCONFIG_DIR=/data/bastillion/ -jar target/bastillion-5.0.0-SNAPSHOT.jar

# 3. Import into the new database (full replace of all 12 tables)
cd tools/migrate
./migrate.sh import /data/bastillion/ ~/bastillion-export.json --yes-replace-all-data

# 4. Delete the export file - it contains decrypted secrets
rm ~/bastillion-export.json