</details>

<details>
<summary><strong>사용자 지정 SSH 키 쌍</strong></summary>

기본적으로 Bastillion은 첫 시작 시 자체 Ed25519 키 쌍을 생성합니다. 자체 키를 사용하려면
UI를 통하는 것이 가장 쉬운 방법입니다: **설정 → 애플리케이션 SSH 키 교체**
(관리자 계정만 가능) — 개인 키, 공개 키, 그리고 비밀번호가 있다면 비밀번호를 붙여넣으면
즉시 적용되며 재시작이 필요 없습니다.

⚠️ 이 작업은 모든 등록된 시스템이 신뢰하는 *하나의* 키를 교체합니다. 이는 Bastillion을 처음
설정할 때, 시스템을 **등록하기 전에** 수행하는 일회성 단계로 의도된 것입니다 — 이미 시스템이
등록되어 있다면, 키를 교체하는 순간 Bastillion은 모든 시스템에 대한 SSH 접근 권한을 잃게
됩니다. 단, 이 정확한 키가 모든 시스템의 `authorized_keys`에 이미 존재하는 경우는 예외입니다.
설정 페이지에서 시스템이 등록된 상태에서는 추가 확인 체크박스를 요구하는 것도 바로 이
때문입니다.

**이미 시스템이 등록되어 있고 키를 교체해야 하나요?** 모든 곳에서 `authorized_keys`를 수동으로
편집하는 대신 Bastillion 자체를 통해 새 키를 사전 배포하세요:

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>Single Sign-On (SAML 2.0)</strong></summary>

엔터프라이즈 ID 공급자(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>

IdP 측에 등록된 Entity ID가 `SAML_BASE_URL`과 정확히 일치할 수 없는 경우에만 필요합니다:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

관리자는 최초 SSO 로그인 시 추가되며 시스템 프로필을 할당받을 수 있습니다.

**Bastillion에 표시되는 사용자 이름:** SAML NameID가 사용자 이름이 됩니다. Entra는 기본적으로
`user.userprincipalname`을 전송하는데, 이는 일반 테넌트 구성원에게는 적합하지만 B2B 게스트(개인 또는
외부 이메일로 로그인하여 게스트로 추가된 사용자)의 경우 `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com`과
같은 지저분한 게스트 UPN을 생성합니다. 더 깔끔한 사용자 이름을 원한다면 엔터프라이즈 애플리케이션의
*Single sign-on* → SAML → *Attributes & Claims*로 이동하여 **Unique User Identifier (Name ID)**를
편집하고 *Source attribute*를 `user.userprincipalname`에서 `user.mail`로 변경하세요.

**역할 매핑이 실제로 작동하는 방식 - 위 LDAP과 동일한 메커니즘:** `SAML_ROLE_ATTRIBUTE`는
사용자의 그룹/역할을 담고 있는 *어떤* assertion 속성인지를 지정합니다. 특정 로그인 시 해당 속성이
보유한 *값*은 **정확한 텍스트 일치**로 **Manage → Profiles** 아래에 생성한 프로필 이름과 비교됩니다.
프로필 이름과 일치하는 값은 사용자를 해당 프로필에 할당하며, 클레임의 다른 부분은 중요하지 않습니다.
따라서 Bastillion 프로필은 assertion이 전송하는 문자열과 정확히 동일한 이름이어야 합니다. 별도의 매핑
단계나 UI는 없으며, 이름만 일치하면 됩니다.

이 부분이 특히 Entra ID에서 가장 자주 문제를 일으키는 부분입니다. 기본적으로 Entra의 그룹 클레임은
엔터프라이즈 애플리케이션의 토큰 구성이 명시적으로 그룹 **이름**을 전송하도록 설정되지 않는 한 각 그룹을
**Object ID**(GUID)로 전송할 수 있습니다. Bastillion 프로필 이름이 `admins`/`everyone`과 같지만
Entra가 GUID를 전송한다면 아무것도 일치하지 않습니다. 매핑이 깨졌다고 가정하기 전에 실제 assertion(또는
앱의 Entra 토큰 구성)에서 실제 클레임 값을 확인하세요. 일반적으로 이 문제이지 Bastillion 측 문제가
아닙니다. 해결 방법은 세 가지이며, 권장 순서대로 나열합니다:

1. **그룹 클레임 대신 Entra App Roles 사용(가장 깔끔함).** 앱 등록 → App roles에서 원하는 정확한
   값(`admins`, `everyone`, ...)으로 역할을 정의한 다음 엔터프라이즈 애플리케이션의 *Users and groups*
   아래에서 사용자/그룹을 해당 역할에 할당합니다. SAML 토큰이 `roles` 클레임을 전송하도록 구성하고
   `SAML_ROLE_ATTRIBUTE`를 그룹 클레임 대신 해당 클레임의 URI를 가리키게 합니다. Entra가 전송하는
   정확한 문자열을 직접 선택할 수 있으므로 GUID 문제가 전혀 없으며, AD 그룹을 재사용하는 것보다 더
   깔끔한 권한 부여 모델입니다.
2. **그룹 클레임의 소스 속성 변경.** 엔터프라이즈 애플리케이션 → Single sign-on → SAML →
   *Attributes & Claims* → Groups 클레임 편집 → *Source attribute* 드롭다운이 있으며 일반적으로
   Group ID가 기본값입니다. 테넌트와 그룹이 클라우드 전용인지 온프레미스 AD에서 동기화되었는지에 따라
   `sAMAccountName` 또는 표시 이름 옵션으로 전환할 수 있습니다. 정확한 선택 항목은 테넌트와 Entra
   포털 버전에 따라 다르므로 특정 라벨을 가정하지 말고 실제로 제공되는 옵션을 확인하세요.
3. **또는 싸우지 말고 Entra가 실제로 전송하는 값으로 Bastillion 프로필 이름을 지정하세요.** Entra가
   GUID 전송을 고집한다면 해당 GUID를 문자 그대로 이름으로 하는 Bastillion 프로필을 만드세요. 덜
   깔끔하지만 Entra 측 재구성이 전혀 필요 없습니다.

클레임이 어떤 Bastillion 프로필과도 일치하지 않는 사용자는 로그인 시 거부됩니다(**Manager** 계정은
유일한 예외이며 프로필 범위에 포함되지 않음) - LDAP과 정확히 동일하므로 위의
`DEFAULT_PROFILE_FOR_SAML`은 `DEFAULT_PROFILE_FOR_LDAP`과 같은 이유로 설정할 가치가 있습니다:
프로필 이름을 IdP의 클레임 값과 맞추는 동안의 안전망입니다.

Bastillion 자체의 일회용 비밀번호(OTP) 확인은 SSO 로그인에서 건너뜁니다. IdP가 자체 MFA/Conditional
Access 정책을 적용할 것으로 예상됩니다. 최초 OTP 등록은 여전히 제공되므로 SSO가 비활성화된 경우 SAML
사용자가 로컬 대체 자격 증명을 사용할 수 있습니다.

**서명된 요청 및 암호화된 assertion:** Bastillion은 필요할 때 처음으로 자체 SAML 서명 인증서를
자동으로 생성하며(TLS 인증서를 생성하는 것과 동일한 방식으로 자체 서명), 이후 모든 발신 AuthnRequest에
서명합니다. 설정이 필요 없으며 IdP가 확인하지 않아도 무해합니다.
`https://bastillion.example.com/saml/metadata`를 가져와 표준 SP 메타데이터 형식으로 해당 인증서를
확보하고, IdP 관리자가 Bastillion의 서명 요청을 확인하거나 Bastillion에 대한 assertion을 암호화해야
하는 경우 해당 인증서를 전달하세요. 대부분의 IdP는 원시 인증서를 붙여넣는 대신 SP 메타데이터 URL을
직접 가져올 수 있습니다. 자동 생성된 키 쌍 대신 실제(예: CA 발급) 키 쌍을 사용하려면
`SAML_SP_KEYSTORE_PATH`/`SAML_SP_KEYSTORE_PASSWORD`를 해당 키가 포함된 PKCS12 키스토어를 가리키게
하세요. 암호화된 assertion을 *요구*하려면(기본적으로 꺼져 있음 - 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