</details>

<details>
<summary><strong>Benutzerdefiniertes SSH-Schlüsselpaar</strong></summary>

Standardmäßig erzeugt Bastillion beim ersten Start sein eigenes Ed25519-Schlüsselpaar. Um ein eigenes
zu verwenden, ist der einfachste Weg über die Benutzeroberfläche: **Einstellungen → Anwendungs-SSH-Schlüssel ersetzen**
(nur Manager-Konten) — fügen Sie einen privaten Schlüssel, einen öffentlichen Schlüssel und ggf. eine Passphrase ein,
und es wird sofort wirksam, ohne Neustart.

⚠️ Dies ersetzt den *einen* Schlüssel, dem jedes registrierte System vertraut. Es ist als einmaliger Schritt
bei der ersten Einrichtung von Bastillion gedacht, **bevor** Sie Systeme registriert haben — wenn Sie bereits
Systeme registriert haben, verliert Bastillion sofort den SSH-Zugriff auf alle, sobald Sie den Schlüssel
ersetzen, es sei denn, genau dieser Schlüssel befindet sich bereits in `authorized_keys` auf jedem einzelnen
von ihnen. Die Einstellungsseite verlangt ein zusätzliches Bestätigungskontrollkästchen, sobald Sie Systeme
registriert haben, genau aus diesem Grund.

**Bereits Systeme registriert und müssen den Schlüssel trotzdem rotieren?** Stellen Sie den neuen Schlüssel
über Bastillion selbst bereit, anstatt `authorized_keys` überall von Hand zu bearbeiten:

1. Setzen Sie `FORCE_USER_KEY_GENERATION=false`, damit **SSH-Schlüssel verwalten → SSH-Schlüssel hinzufügen** es Ihnen erlaubt,
   einen vorhandenen öffentlichen Schlüssel einzufügen, anstatt nur einen neuen zu erzeugen.
2. Fügen Sie den neuen Schlüssel dort gegen ein Profil hinzu, das alle Ihre Systeme abdeckt, und bestätigen Sie (unter
   SSH-Schlüssel verwalten oder im Status jedes Systems), dass er tatsächlich überall angekommen ist — beachten Sie
   `AUTH_KEYS_REFRESH_INTERVAL`, da dies das ist, was ihn ausrollt.
3. Erst wenn Sie sicher sind, dass er auf jedem System ist, ersetzen Sie den Anwendungsschlüssel in den Einstellungen.
4. Setzen Sie `FORCE_USER_KEY_GENERATION` auf seinen vorherigen Wert zurück, und sobald Sie bestätigt haben,
   dass der neue Anwendungsschlüssel auf jedes System übertragen wurde (auch hier beachten Sie
   `AUTH_KEYS_REFRESH_INTERVAL`), entfernen Sie den in Schritt 2 hinzugefügten Schlüssel aus SSH-Schlüssel verwalten —
   er wurde dort nur zur Vorbereitung von `authorized_keys` bereitgestellt und wird künftig nicht mehr benötigt.

Für skriptbasierte/headless Einrichtungen kann dasselbe stattdessen über Umgebungsvariablen und einen
Neustart erfolgen:```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>Datenbankeinstellungen</strong></summary>

Eingebettetes H2-Beispiel:```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>Externe Authentifizierung (LDAP / JAAS)</strong></summary>

Authentifizierung gegen einen bestehenden LDAP/Active-Directory-Server anstelle von (oder zusätzlich zu) lokalen
Passwörtern. Aktivieren Sie es:```bash
export JAAS_MODULE=ldap-ol

Um LDAP-Rollen Bastillion-Profilen zuzuordnen:```
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>

Authentifizieren Sie sich gegen einen Unternehmens-Identitätsanbieter – Microsoft Entra ID, Okta, ADFS oder einen beliebigen
SAML-2.0-IdP – anstelle von (oder zusätzlich zu) lokalen Passwörtern oder LDAP. Sobald dies konfiguriert ist, erscheint auf der Anmeldeseite eine Schaltfläche **Mit SSO anmelden**. Aktivieren Sie sie:```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>

Nur erforderlich, wenn die auf der IdP-Seite registrierte Entity-ID nicht exakt mit `SAML_BASE_URL` übereinstimmen kann:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

Admins werden beim ersten SSO-Login hinzugefügt und können Systemprofile zugewiesen bekommen.

**In Bastillion angezeigter Benutzername:** Die SAML-NameID wird zum Benutzernamen. Entra sendet
standardmäßig `user.userprincipalname`, was für reguläre Tenant-Mitglieder in Ordnung ist, aber für
B2B-Gäste (alle, die mit einer persönlichen oder externen E-Mail als Gast angemeldet sind) eine
hässliche Gast-UPN wie `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com` erzeugt. Für einen
saubereren Benutzernamen gehen Sie zur *Single sign-on*-Konfiguration der Enterprise Application →
SAML → *Attributes & Claims*, bearbeiten Sie **Unique User Identifier (Name ID)** und ändern Sie
deren *Source attribute* von `user.userprincipalname` auf `user.mail`.

**So funktioniert das Rollen-Mapping tatsächlich – gleicher Mechanismus wie bei LDAP oben:** `SAML_ROLE_ATTRIBUTE`
benennt *welches* Assertion-Attribut die Gruppen/Rollen des Benutzers trägt; welche *Werte* dieses
Attribut bei einem bestimmten Login enthält, werden **per exaktem Textabgleich** mit den Namen der
Profile verglichen, die Sie unter **Manage → Profiles** erstellt haben. Ein Wert, der mit einem
Profilnamen übereinstimmt, weist den Benutzer diesem zu; nichts anderes an der Claim ist relevant.
Ein Bastillion-Profil muss also exakt genauso heißen wie die Zeichenfolge, die die Assertion sendet –
es gibt keinen separaten Mapping-Schritt oder eine UI, die Namen müssen nur übereinstimmen.

Das ist der Teil, der bei Entra ID am häufigsten für Verwirrung sorgt: Standardmäßig kann der
Gruppen-Claim von Entra jede Gruppe als **Object ID** (eine GUID) ausgeben statt als Anzeigenamen,
sofern die Token-Konfiguration der Enterprise Application nicht explizit auf die Ausgabe von
Gruppen-**namen** eingestellt ist. Wenn Ihre Bastillion-Profile Namen wie `admins`/`everyone` tragen,
Entra aber GUIDs sendet, wird nie etwas übereinstimmen. Prüfen Sie den tatsächlichen Claim-Wert in
einer echten Assertion (oder der Token-Konfiguration von Entra für die App), bevor Sie annehmen, das
Mapping sei defekt – meist liegt es daran und nicht an einem Bastillion-seitigen Problem. Drei Wege,
das zu beheben, in der Reihenfolge unserer Empfehlung:

1. **Entra-App-Rollen statt Gruppen-Claims verwenden (am saubersten).** Unter der App-Registrierung →
   App roles definieren Sie Rollen mit exakt den gewünschten Werten (`admins`, `everyone`, ...) und
   weisen dann Benutzer/Gruppen diesen Rollen unter *Users and groups* der Enterprise Application zu.
   Konfigurieren Sie das SAML-Token so, dass es den `roles`-Claim ausgibt, und richten Sie
   `SAML_ROLE_ATTRIBUTE` auf die URI dieses Claims statt auf den Gruppen-Claim. Sie wählen die exakte
   Zeichenfolge, die Entra sendet – kein GUID-Problem, und es ist ohnehin ein saubereres
   Autorisierungsmodell als die Zweckentfremdung von AD-Gruppen.
2. **Das Source-Attribut des Gruppen-Claims ändern.** Enterprise Application → Single sign-on →
   SAML → *Attributes & Claims* → Gruppen-Claim bearbeiten → dort gibt es ein *Source attribute*-
   Dropdown, normalerweise standardmäßig auf Group ID eingestellt. Je nach Tenant und ob die Gruppen
   Cloud-only sind oder aus lokalem AD synchronisiert werden, können Sie es möglicherweise auf
   `sAMAccountName` oder eine Anzeigenamen-Option umstellen – die genauen Optionen variieren je nach
   Tenant und Entra-Portalversion, prüfen Sie also, was tatsächlich angeboten wird, statt eine
   bestimmte Bezeichnung anzunehmen.
3. **Oder kämpfen Sie nicht dagegen – benennen Sie das Bastillion-Profil nach dem, was Entra
   tatsächlich sendet.** Wenn Entra darauf besteht, die GUID zu senden, erstellen Sie ein
   Bastillion-Profil, das wörtlich diese GUID als Namen trägt. Hässlicher, erfordert aber keinerlei
   Entra-seitige Neukonfiguration.

Ein Benutzer, dessen Claims zu keinem Bastillion-Profil passen, wird beim Login abgewiesen
(**Manager**-Konten sind die eine Ausnahme; sie sind nicht profilgebunden) – genau wie bei LDAP,
weshalb `DEFAULT_PROFILE_FOR_SAML` oben aus demselben Grund sinnvoll ist wie
`DEFAULT_PROFILE_FOR_LDAP`: als Sicherheitsnetz, während Sie Profilnamen noch mit den Claim-Werten
Ihres IdP abgleichen.

Bastillions eigene Einmalpasswort-Prüfung wird bei SSO-Logins übersprungen – der IdP soll seine
eigene MFA-/Conditional-Access-Richtlinie durchsetzen. Die erstmalige OTP-Registrierung wird
trotzdem angeboten, damit SAML-Benutzer eine lokale Fallback-Anmeldeinformation haben, falls SSO
jemals deaktiviert wird.

**Signierte Anfragen und verschlüsselte Assertions:** Bastillion generiert sein eigenes
SAML-Signaturzertifikat automatisch (selbstsigniert, auf dieselbe Weise wie sein TLS-Zertifikat),
sobald es zum ersten Mal benötigt wird, und signiert damit von da an jede ausgehende AuthnRequest –
keine Einrichtung erforderlich und harmlos, selbst wenn Ihr IdP es nicht prüft. Rufen Sie
`https://bastillion.example.com/saml/metadata` ab, um dieses Zertifikat in standardmäßiger
SP-Metadatenform zu erhalten, und geben Sie es Ihrem IdP-Administrator, falls dieser Bastillions
signierte Anfragen verifizieren oder Assertions für Bastillion verschlüsseln soll – die meisten IdPs
können eine SP-Metadaten-URL direkt importieren, statt ein rohes Zertifikat einzufügen. Wenn Sie
statt des automatisch generierten lieber ein echtes (z. B. CA-ausgestelltes) Schlüsselpaar verwenden
möchten, richten Sie `SAML_SP_KEYSTORE_PATH`/`SAML_SP_KEYSTORE_PASSWORD` auf einen PKCS12-Keystore,
der es enthält. Um verschlüsselte Assertions zu *erzwingen* (standardmäßig deaktiviert – aktivieren
Sie dies erst, wenn Ihr IdP tatsächlich so konfiguriert ist, dass er für Bastillions Zertifikat
verschlüsselt, sonst schlagen alle Logins fehl):```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

Es gibt auch ein dateibasiertes Audit-Protokoll, das standardmäßig deaktiviert ist. Aktivieren Sie es in **log4j2.xml**, indem Sie
Folgendes auskommentieren:
- `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>Migration von v4</strong></summary>

Sie möchten von einer alten Bastillion-v4-Installation upgraden und Ihre Benutzer, Systeme, Profile,
Skripte und (am wichtigsten) das vorhandene SSH-Schlüsselpaar der Anwendung behalten, anstatt von
vorn zu beginnen? `tools/migrate/` enthält ein eigenständiges Migrationstool genau für diesen Zweck – es exportiert jede
Tabelle aus der alten H2-Datenbank (wobei die auf App-Ebene verschlüsselten Spalten mit dem Keystore der ALTEN
Instanz entschlüsselt werden) in eine JSON-Datei und importiert sie dann in eine frische v5-Instanz (wobei sie mit
dem Keystore der NEUEN Instanz erneut verschlüsselt werden). Vorhandene Benutzer können sich unmittelbar danach
mit ihren aktuellen Passwörtern anmelden – ohne erzwungene Zurücksetzungen.```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