</details>

<details>
<summary><strong>カスタムSSHキーペア</strong></summary>

デフォルトでは、Bastillionは初回起動時に独自のEd25519キーペアを生成します。独自のキーを使用するには、
UI経由が最も簡単です：**設定 → アプリケーションSSHキーの置き換え**
（マネージャーアカウントのみ）— 秘密鍵、公開鍵、およびパスフレーズ（ある場合）を貼り付けると、
再起動不要ですぐに反映されます。

⚠️ これにより、登録済みのすべてのシステムが信頼する*1つの*キーが置き換えられます。これは、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>シングルサインオン（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になります。
よりすっきりしたユーザー名にするには、エンタープライズアプリケーションの *シングルサインオン* →
SAML → *属性とクレーム* に移動し、**一意のユーザー識別子（Name ID）** を編集して、
その *ソース属性* を `user.userprincipalname` から `user.mail` に変更します。

**ロールマッピングの実際の仕組み - 上記のLDAPと同じメカニズム:** `SAML_ROLE_ATTRIBUTE` は、
ユーザーのグループ/ロールを運ぶ *どの* アサーション属性かを指定します。特定のログインでその属性が
保持する *値* は、**完全なテキスト一致** で、**管理 → プロファイル** の下に作成したプロファイルの
名前と比較されます。プロファイル名に一致する値はユーザーをそのプロファイルに割り当てます。
クレームの他の部分は関係ありません。つまり、Bastillionプロファイルは、アサーションが送信する
文字列と完全に同じ名前である必要があります。個別のマッピング手順やUIはなく、名前が一致している
必要があるだけです。

これは特にEntra IDで最も頻繁に問題を引き起こす部分です。デフォルトでは、Entraのグループクレームは、
エンタープライズアプリケーションのトークン構成がグループ**名**を送信するように明示的に設定されていない限り、
各グループを表示名ではなく**オブジェクトID**（GUID）として送信できます。Bastillionプロファイルに
`admins`/`everyone` のような名前を付けていても、EntraがGUIDを送信している場合、何も一致しません。
マッピングが壊れていると判断する前に、実際のアサーション（またはアプリのEntraトークン構成）で実際の
クレーム値を確認してください。通常はこれが原因であり、Bastillion側の問題ではありません。
修正方法は3つあり、推奨順に示します。

1. **グループクレームの代わりにEntraアプリロールを使用する（最もクリーン）。** アプリの登録 →
   アプリロールで、必要な値（`admins`、`everyone` など）とまったく同じロールを定義し、
   エンタープライズアプリケーションの *ユーザーとグループ* でユーザー/グループをそれらのロールに
   割り当てます。SAMLトークンが `roles` クレームを送信するように構成し、`SAML_ROLE_ATTRIBUTE` を
   グループクレームではなくそのクレームのURIに向けます。Entraが送信する正確な文字列を選択できるため、
   GUIDの問題はまったくなく、ADグループを流用するよりもクリーンな認可モデルになります。
2. **グループクレームのソース属性を変更する。** エンタープライズアプリケーション → シングルサインオン →
   SAML → *属性とクレーム* → グループクレームを編集 → *ソース属性* ドロップダウンがあり、
   通常はグループIDがデフォルトです。テナントと、グループがクラウドのみかオンプレミスADから同期されているか
   によって、`sAMAccountName` または表示名オプションに切り替えられる場合があります。正確な選択肢は
   テナントとEntraポータルのバージョンによって異なるため、特定のラベルを想定せずに実際に提供されている
   ものを確認してください。
3. **または、争わずに、Entraが実際に送信するものに合わせてBastillionプロファイルに名前を付ける。**
   EntraがGUIDの送信を主張する場合、そのGUIDを文字通り名前にしたBastillionプロファイルを作成します。
   見た目は悪いですが、Entra側の再構成はゼロで済みます。

クレームがどのBastillionプロファイルにも一致しないユーザーは、ログイン時に拒否されます
（**Manager** アカウントは唯一の例外で、プロファイルスコープの対象外です）。LDAPとまったく同じなので、
`DEFAULT_PROFILE_FOR_SAML` を設定する価値があるのは、`DEFAULT_PROFILE_FOR_LDAP` を設定するのと同じ理由です。
プロファイル名をIdPのクレーム値に合わせている間のセーフティネットです。

SSOログインでは、Bastillion独自のワンタイムパスコードチェックはスキップされます。IdPが独自の
MFA/条件付きアクセスポリシーを適用することが期待されます。初回のOTP登録は引き続き提供されるため、
SSOが無効になった場合に備えてSAMLユーザーはローカルのフォールバック認証情報を利用できます。

**署名付きリクエストと暗号化されたアサーション:** Bastillionは、最初に必要になったときに独自の
SAML署名証明書を自動的に生成し（自己署名、TLS証明書の生成と同じ方法）、以降はそれを使用してすべての
送信AuthnRequestに署名します。セットアップは不要で、IdPがチェックしなくても無害です。
`https://bastillion.example.com/saml/metadata` を取得して、その証明書を標準のSPメタデータ形式で入手し、
Bastillionの署名付きリクエストを検証する必要がある場合や、Bastillion用にアサーションを暗号化する必要が
ある場合は、IdP管理者に渡します。ほとんどのIdPは、生の証明書を貼り付ける代わりにSPメタデータURLを直接
インポートできます。自動生成されたものの代わりに実際の（例：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 データベースのすべてのテーブルを（アプリレベルの暗号化された列を OLD インスタンスのキーストアで復号化して）JSON ファイルにエクスポートし、それを新しい v5 インスタンスにインポートします（NEW インスタンスのキーストアで再暗号化）。既存のユーザーは、強制的なリセットなしで、移行直後に現在のパスワードでログインできます。```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