</details>

<details>
<summary><strong>Coppia di Chiavi SSH Personalizzata</strong></summary>

Per impostazione predefinita, Bastillion genera la propria coppia di chiavi Ed25519 al primo avvio. Per utilizzarne una propria,
il modo più semplice è tramite l'interfaccia: **Impostazioni → Sostituisci Chiave SSH dell'Applicazione**
(solo account manager) — incolla una chiave privata, una chiave pubblica e una passphrase se presente,
e l'effetto è immediato, senza bisogno di riavvio.

⚠️ Questa operazione sostituisce l'*unica* chiave di cui ogni sistema registrato si fida. È pensata come un passaggio da eseguire una sola volta
durante la configurazione iniziale di Bastillion, **prima** di registrare qualsiasi sistema — se hai già
sistemi registrati, Bastillion perde l'accesso SSH a tutti loro nell'istante in cui sostituisci
la chiave, a meno che questa chiave esatta non sia già presente in `authorized_keys` su ciascuno di essi
prima. La pagina Impostazioni richiede una casella di conferma aggiuntiva una volta che hai sistemi
registrati, proprio per questo motivo.

**Hai già sistemi registrati e devi comunque ruotare la chiave?** Pre-distribuisci la nuova chiave
tramite Bastillion stesso invece di modificare `authorized_keys` manualmente ovunque:

1. Imposta `FORCE_USER_KEY_GENERATION=false` così che **Gestisci Chiavi SSH → Aggiungi Chiave SSH** ti permetta di incollare
   una chiave pubblica esistente invece di generarne solo una nuova.
2. Aggiungi lì la nuova chiave su un profilo che copra tutti i tuoi sistemi e conferma (sotto
   Gestisci Chiavi SSH, o nello stato di ciascun sistema) che sia effettivamente distribuita ovunque — tieni presente
   `AUTH_KEYS_REFRESH_INTERVAL`, poiché è ciò che la propaga.
3. Solo quando sei certo che sia su ogni sistema, sostituisci la chiave dell'applicazione nelle Impostazioni.
4. Riporta `FORCE_USER_KEY_GENERATION` al suo valore precedente, poi una volta confermato
   che la nuova chiave dell'applicazione si è propagata a ogni sistema (di nuovo, considera
   `AUTH_KEYS_REFRESH_INTERVAL`), rimuovi la chiave aggiunta al punto 2 da Gestisci Chiavi SSH —
   era solo in staging lì per pre-popolare `authorized_keys` e non serve più in futuro.

Per configurazioni scriptate/senza interfaccia, la stessa operazione può essere eseguita tramite variabili d'ambiente e un
riavvio invece:```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>Impostazioni del Database</strong></summary>

Esempio H2 integrato:```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>Autenticazione Esterna (LDAP / JAAS)</strong></summary>

Autentica tramite un server LDAP/Active Directory esistente invece delle (o in aggiunta alle) password
locali. Per abilitarla:```bash
export JAAS_MODULE=ldap-ol

Per mappare i ruoli LDAP ai profili 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>

Autentica tramite un provider di identità aziendale - Microsoft Entra ID, Okta, ADFS o qualsiasi
IdP SAML 2.0 - invece di (o in aggiunta a) password locali o LDAP. Un pulsante **Accedi con SSO**
appare nella pagina di login una volta configurato. Abilitalo:```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>

Solo necessario se l'Entity ID registrato sul lato IdP non può corrispondere esattamente a `SAML_BASE_URL`:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

Gli amministratori vengono aggiunti al primo accesso SSO e possono ricevere profili di sistema.

**Nome utente mostrato in Bastillion:** il SAML NameID diventa il nome utente. Entra invia
`user.userprincipalname` per impostazione predefinita, il che va bene per i membri regolari del tenant ma produce un
UPN ospite poco elegante come `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com` per gli ospiti B2B (chiunque
abbia effettuato l'accesso con un'email personale o esterna aggiunta come ospite). Per un nome utente più pulito, vai su
*Single sign-on* dell'Enterprise Application → SAML → *Attributes & Claims*, modifica **Unique
User Identifier (Name ID)** e cambia il suo *Source attribute* da `user.userprincipalname`
a `user.mail`.

**Come funziona realmente il mapping dei ruoli - stesso meccanismo dell'LDAP sopra:** `SAML_ROLE_ATTRIBUTE`
indica *quale* attributo dell'asserzione trasporta i gruppi/ruoli dell'utente; qualunque *valore* quell'attributo
contenga in un dato accesso viene confrontato, **per corrispondenza testuale esatta**, con i nomi dei
Profili che hai creato sotto **Manage → Profiles**. Un valore che corrisponde a un nome di profilo
assegna l'utente a quel profilo; nient'altro dell'asserzione conta. Quindi un profilo Bastillion deve essere
denominato esattamente come la stringa che l'asserzione invia - non esiste un passaggio di mapping separato
né un'interfaccia, i nomi devono semplicemente coincidere.

Questa è la parte che più spesso crea problemi con Entra ID in particolare: per
impostazione predefinita, l'asserzione dei gruppi di Entra può emettere ogni gruppo come **Object ID** (un GUID) piuttosto che come nome
visualizzato, a meno che la configurazione del token dell'Enterprise Application non sia impostata esplicitamente per emettere i **nomi** dei gruppi. Se i tuoi profili Bastillion sono denominati
come `admins`/`everyone` ma Entra sta inviando GUID, non corrisponderà mai nulla. Controlla il valore effettivo dell'asserzione in un'asserzione reale (o
la configurazione del token di Entra per l'app) prima di presumere che il mapping sia rotto - di solito è
questo, non un problema lato Bastillion. Tre modi per risolverlo, in ordine di ciò che consigliamo:

1. **Usa Entra App Roles invece delle asserzioni di gruppo (il più pulito).** Sotto la registrazione dell'app →
   App roles, definisci ruoli con esattamente i valori che desideri (`admins`, `everyone`, ...), poi
   assegna utenti/gruppi a quei ruoli sotto *Users and groups* dell'Enterprise Application.
   Configura il token SAML per emettere l'asserzione `roles` e punta `SAML_ROLE_ATTRIBUTE` a quell'asserzione
   URI invece dell'asserzione dei gruppi. Scegli tu la stringa esatta che Entra invia - nessun problema
   di GUID, ed è comunque un modello di autorizzazione più pulito che riutilizzare i gruppi AD.
2. **Cambia l'attributo sorgente dell'asserzione dei gruppi.** Enterprise Application → Single sign-on →
   SAML → *Attributes & Claims* → modifica l'asserzione Groups → c'è un menu a tendina *Source attribute*,
   normalmente impostato su Group ID. A seconda del tuo tenant e se i gruppi
   sono solo cloud o sincronizzati da AD locale, potresti poterlo cambiare in `sAMAccountName`
   o un'opzione di nome visualizzato - le scelte esatte variano in base al tenant e alla versione del portale Entra, quindi controlla
   cosa viene effettivamente offerto piuttosto che presumere un'etichetta specifica.
3. **Oppure non combatterlo - denomina il profilo Bastillion in base a ciò che Entra invia effettivamente.** Se
   Entra insiste nell'inviare il GUID, crea un profilo Bastillion letteralmente denominato con quel GUID.
   Più brutto, ma richiede zero riconfigurazione lato Entra.

Un utente le cui asserzioni non corrispondono a nessun profilo Bastillion viene rifiutato all'accesso (gli account **Manager** sono
l'unica eccezione; non sono limitati ai profili) - esattamente come con LDAP, quindi
`DEFAULT_PROFILE_FOR_SAML` sopra vale la pena impostarlo per lo stesso motivo per cui
`DEFAULT_PROFILE_FOR_LDAP` lo è: una rete di sicurezza mentre stai ancora allineando i nomi dei profili con
i valori delle asserzioni del tuo IdP.

Il controllo della password monouso di Bastillion viene saltato per gli accessi SSO - ci si aspetta che l'IdP
applichi la propria politica MFA/Conditional Access. La registrazione iniziale dell'OTP viene comunque
offerta così gli utenti SAML hanno una credenziale di fallback locale disponibile se SSO viene mai disabilitato.

**Richieste firmate e asserzioni crittografate:** Bastillion genera il proprio certificato di firma SAML
automaticamente (self-signed, allo stesso modo in cui genera il suo certificato TLS) la
prima volta che serve, e firma ogni AuthnRequest in uscita con esso da quel momento in poi - nessuna
configurazione richiesta, e innocuo anche se il tuo IdP non lo verifica. Recupera
`https://bastillion.example.com/saml/metadata` per ottenere quel certificato in formato standard
SP metadata e consegnalo all'amministratore del tuo IdP se devono verificare le richieste firmate di Bastillion,
o se devono crittografare le asserzioni per Bastillion - la maggior parte degli IdP può importare un URL SP metadata
direttamente invece di incollare un certificato grezzo. Se preferisci usare una coppia di chiavi reale (es.
emessa da CA) invece di quella auto-generata, punta `SAML_SP_KEYSTORE_PATH`/
`SAML_SP_KEYSTORE_PASSWORD` a un keystore PKCS12 che la contiene. Per *richiedere* asserzioni
crittografate (disattivato per impostazione predefinita - attivalo solo una volta che il tuo IdP è effettivamente configurato per
crittografare per il certificato di Bastillion, o ogni accesso inizierà a fallire):```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

È inoltre disponibile un log di audit basato su file, disabilitato per impostazione predefinita. Abilitalo in **log4j2.xml** rimuovendo il commento da:
- `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>Migrazione da v4</strong></summary>

Stai effettuando l'upgrade da una vecchia installazione di Bastillion v4 e vuoi mantenere i tuoi utenti, sistemi, profili, script e (soprattutto) la coppia di chiavi SSH esistente dell'applicazione invece di ricominciare da zero? `tools/migrate/` contiene uno strumento di migrazione autonomo progettato esattamente per questo: esporta ogni tabella dal vecchio database H2 (decrittando le colonne crittografate a livello di applicazione con il keystore della vecchia istanza) in un file JSON, quindi lo importa in una nuova istanza v5 (ricrittando con il keystore della NUOVA istanza). Gli utenti esistenti possono accedere con le loro password attuali immediatamente dopo, senza reimpostazioni forzate.```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