</details>

<details>
<summary><strong>Par de claves SSH personalizado</strong></summary>

De forma predeterminada, Bastillion genera su propio par de claves Ed25519 en el primer arranque. Para usar el tuyo propio,
la forma más sencilla es a través de la interfaz: **Configuración → Reemplazar clave SSH de la aplicación**
(solo cuentas de administrador): pega una clave privada, una clave pública y una frase de contraseña si la tiene,
y surte efecto de inmediato, sin necesidad de reiniciar.

⚠️ Esto reemplaza la *única* clave que todos los sistemas registrados confían. Está pensado como un paso único
al configurar Bastillion por primera vez, **antes** de registrar cualquier sistema. Si ya
tienes sistemas registrados, Bastillion pierde el acceso SSH a todos ellos en el instante en que reemplazas
la clave, a menos que esta clave exacta ya esté presente en `authorized_keys` en cada uno de ellos
primero. La página de Configuración requiere una casilla de confirmación adicional una vez que tienes sistemas
registrados, precisamente por esto.

**¿Ya tienes sistemas registrados y necesitas rotar la clave de todos modos?** Preconfigura la nueva clave
a través del propio Bastillion en lugar de editar `authorized_keys` manualmente en todas partes:

1. Establece `FORCE_USER_KEY_GENERATION=false` para que **Administrar claves SSH → Agregar clave SSH** te permita pegar
   una clave pública existente en lugar de solo generar una nueva.
2. Agrega la nueva clave allí contra un perfil que cubra todos tus sistemas y confirma (en
   Administrar claves SSH, o en el estado de cada sistema) que realmente se haya distribuido en todos ellos: ten en cuenta
   `AUTH_KEYS_REFRESH_INTERVAL`, ya que es lo que la propaga.
3. Solo cuando estés seguro de que está en todos los sistemas, reemplaza la clave de la aplicación en Configuración.
4. Restablece `FORCE_USER_KEY_GENERATION` a su valor anterior y, una vez que hayas confirmado
   que la nueva clave de la aplicación se ha propagado a todos los sistemas (de nuevo, ten en cuenta
   `AUTH_KEYS_REFRESH_INTERVAL`), elimina la clave que agregaste en el paso 2 de Administrar claves SSH:
   solo se preparó allí para presemillar `authorized_keys` y no se necesita de aquí en adelante.

Para configuraciones mediante scripts/sin interfaz, lo mismo se puede hacer con variables de entorno y un
reinicio en su lugar:```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>Configuración de la base de datos</strong></summary>

Ejemplo con H2 integrado:```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>Autenticación externa (LDAP / JAAS)</strong></summary>

Autenticar contra un servidor LDAP/Active Directory existente en lugar de (o además de) las
contraseñas locales. Actívalo:```bash
export JAAS_MODULE=ldap-ol

Para mapear roles de LDAP a perfiles de 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>Inicio de sesión único (SAML 2.0)</strong></summary>

Autentíquese contra un proveedor de identidad empresarial (Microsoft Entra ID, Okta, ADFS o cualquier
IdP SAML 2.0) en lugar de (o además de) contraseñas locales o LDAP. Un botón **Iniciar sesión con SSO**
aparece en la página de inicio de sesión una vez configurado. Actívelo:```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 es necesario si el Entity ID registrado en el lado del IdP no puede coincidir exactamente con `SAML_BASE_URL`:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

Los administradores se añaden en el primer inicio de sesión SSO y se les pueden asignar perfiles de sistema.

**Nombre de usuario mostrado en Bastillion:** el SAML NameID se convierte en el nombre de usuario. Entra envía
`user.userprincipalname` por defecto, lo cual está bien para miembros habituales del inquilino, pero produce un
UPN de invitado poco elegante como `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com` para invitados B2B (cualquier persona
que haya iniciado sesión con un correo personal o externo añadido como invitado). Para un nombre de usuario más limpio, ve a
la *Single sign-on* de la Aplicación Empresarial → SAML → *Attributes & Claims*, edita **Unique
User Identifier (Name ID)** y cambia su *Source attribute* de `user.userprincipalname`
a `user.mail`.

**Cómo funciona realmente el mapeo de roles - el mismo mecanismo que con LDAP arriba:** `SAML_ROLE_ATTRIBUTE`
nombra *qué* atributo de aserción transporta los grupos/roles del usuario; los *valores* que ese
atributo contenga en un inicio de sesión concreto se comparan, **por coincidencia exacta de texto**, con los nombres de
los Perfiles que hayas creado en **Manage → Profiles**. Un valor que coincida con un nombre de perfil
asigna el usuario a ese perfil; nada más sobre la reclamación importa. Así que un perfil de Bastillion debe llamarse
exactamente igual que la cadena que envía la aserción - no hay un paso de mapeo separado
ni una interfaz, los nombres solo tienen que coincidir.

Esta es la parte que más a menudo confunde a la gente con Entra ID específicamente: por defecto,
la reclamación de grupos de Entra puede emitir cada grupo como su **Object ID** (un GUID) en lugar de su nombre
para mostrar, a menos que la configuración de token de la Aplicación Empresarial esté explícitamente configurada para emitir **nombres**
de grupo. Si tus perfiles de Bastillion se llaman cosas como `admins`/`everyone` pero Entra está
enviando GUIDs, nada coincidirá nunca. Comprueba el valor real de la reclamación en una aserción auténtica (o
la configuración de token de Entra para la aplicación) antes de asumir que el mapeo está roto - normalmente es
esto, no un problema del lado de Bastillion. Tres formas de solucionarlo, en orden de lo que recomendamos:

1. **Usa App Roles de Entra en lugar de reclamaciones de grupos (lo más limpio).** En el registro de la aplicación →
   App roles, define roles con exactamente los valores que quieras (`admins`, `everyone`, ...), y luego
   asigna usuarios/grupos a esos roles en *Users and groups* de la Aplicación Empresarial.
   Configura el token SAML para emitir la reclamación `roles` y apunta `SAML_ROLE_ATTRIBUTE` a esa
   URI de reclamación en lugar de a la reclamación de grupos. Tú eliges la cadena exacta que envía Entra - sin problema
   de GUID en absoluto, y es un modelo de autorización más limpio que reutilizar grupos de AD de todos modos.
2. **Cambia el atributo de origen de la reclamación de grupos.** Aplicación Empresarial → Single sign-on →
   SAML → *Attributes & Claims* → edita la reclamación de Groups → hay un desplegable
   *Source attribute*, normalmente con Group ID por defecto. Dependiendo de tu inquilino y de si los grupos
   son solo en la nube o están sincronizados desde AD local, puede que puedas cambiarlo a `sAMAccountName`
   o a una opción de nombre para mostrar - las opciones exactas varían según el inquilino y la versión del portal de Entra, así que
   comprueba lo que realmente se ofrece en lugar de asumir una etiqueta específica.
3. **O no luches contra ello - nombra el perfil de Bastillion según lo que Entra envíe realmente.** Si
   Entra insiste en enviar el GUID, crea un perfil de Bastillion literalmente llamado con ese GUID.
   Más feo, pero requiere cero reconfiguración del lado de Entra.

Un usuario cuyas reclamaciones no coincidan con ningún perfil de Bastillion es rechazado al iniciar sesión (las cuentas **Manager** son
la única excepción; no están limitadas por perfil) - exactamente igual que con LDAP, así que
`DEFAULT_PROFILE_FOR_SAML` arriba merece la pena configurarlo por la misma razón
que `DEFAULT_PROFILE_FOR_LDAP`: una red de seguridad mientras sigues alineando los nombres de perfil con
los valores de reclamación de tu IdP.

La comprobación de contraseña de un solo uso (OTP) propia de Bastillion se omite para inicios de sesión SSO - se espera que el IdP
aplique su propia política de MFA/Conditional Access en su lugar. El registro OTP de primera vez se sigue
ofreciendo para que los usuarios SAML tengan una credencial de respaldo local disponible si el SSO se desactiva alguna vez.

**Solicitudes firmadas y aserciones cifradas:** Bastillion genera su propio certificado de firma SAML
automáticamente (autofirmado, de la misma manera que genera su certificado TLS) la primera
vez que se necesita, y firma cada AuthnRequest saliente con él a partir de entonces - sin
configuración requerida, e inofensivo incluso si tu IdP no lo comprueba. Obtén
`https://bastillion.example.com/saml/metadata` para conseguir ese certificado en formato estándar
de metadatos SP y entrégalo a tu administrador del IdP si deben verificar las solicitudes firmadas de Bastillion,
o deben cifrar aserciones para Bastillion - la mayoría de los IdP pueden importar una URL de metadatos SP
directamente en lugar de pegar un certificado en bruto. Si prefieres usar un par de claves real (p. ej.
emitido por una CA) en lugar del generado automáticamente, apunta `SAML_SP_KEYSTORE_PATH`/
`SAML_SP_KEYSTORE_PASSWORD` a un almacén de claves PKCS12 que lo contenga. Para *exigir* aserciones
cifradas (desactivado por defecto - solo actívalo una vez que tu IdP esté realmente configurado para
cifrar para el certificado de Bastillion, o cada inicio de sesión empezará a fallar):```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

También existe un registro de auditoría basado en archivos, deshabilitado por defecto. Actívalo en **log4j2.xml** descomentando:
- `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>Migración desde v4</strong></summary>

¿Estás actualizando desde una instalación antigua de Bastillion v4 y quieres conservar tus usuarios, sistemas, perfiles,
scripts y (lo más importante) el par de claves SSH existente de la aplicación en lugar de empezar
de cero? `tools/migrate/` incluye una herramienta de migración independiente exactamente para eso: exporta cada
tabla de la antigua base de datos H2 (descifrando las columnas cifradas a nivel de aplicación con el
almacén de claves de la instancia ANTIGUA) a un archivo JSON, y luego la importa en una instancia nueva de v5 (volviendo a cifrar
con el almacén de claves de la instancia NUEVA). Los usuarios existentes pueden iniciar sesión con sus contraseñas actuales
inmediatamente después — sin restablecimientos forzados.```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