</details>

<details>
<summary><strong>Par de Chaves SSH Personalizado</strong></summary>

Por padrão, o Bastillion gera seu próprio par de chaves Ed25519 na primeira inicialização. Para usar o seu próprio,
a maneira mais fácil é pela interface: **Configurações → Substituir Chave SSH do Aplicativo**
(apenas contas de administrador) — cole uma chave privada, uma chave pública e uma frase secreta, se houver,
e a alteração entra em vigor imediatamente, sem necessidade de reinicialização.

⚠️ Isso substitui a *única* chave que todos os sistemas registrados confiam. É destinada a uma etapa única
na configuração inicial do Bastillion, **antes** de você registrar qualquer sistema — se você já
tiver sistemas registrados, o Bastillion perde o acesso SSH a todos eles no instante em que você substituir
a chave, a menos que essa chave exata já esteja presente em `authorized_keys` em cada um deles
primeiro. A página de Configurações exige uma caixa de confirmação extra quando você já tem sistemas
registrados, justamente por causa disso.

**Já tem sistemas registrados e precisa rotacionar a chave mesmo assim?** Pré-cadastre a nova chave
através do próprio Bastillion, em vez de editar `authorized_keys` manualmente em todos os lugares:

1. Defina `FORCE_USER_KEY_GENERATION=false` para que **Gerenciar Chaves SSH → Adicionar Chave SSH** permita colar
   uma chave pública existente em vez de apenas gerar uma nova.
2. Adicione a nova chave lá em um perfil que cubra todos os seus sistemas e confirme (em
   Gerenciar Chaves SSH, ou no status de cada sistema) que ela realmente foi aplicada em todos — lembre-se
   de `AUTH_KEYS_REFRESH_INTERVAL`, pois é isso que a distribui.
3. Somente quando tiver certeza de que está em todos os sistemas, substitua a chave do aplicativo em Configurações.
4. Defina `FORCE_USER_KEY_GENERATION` de volta ao valor anterior e, depois de confirmar
   que a nova chave do aplicativo foi propagada para todos os sistemas (novamente, atente para
   `AUTH_KEYS_REFRESH_INTERVAL`), remova a chave adicionada no passo 2 em Gerenciar Chaves SSH —
   ela foi apenas pré-cadastrada ali para pré-popular `authorized_keys` e não é necessária daqui em diante.

Para configurações via script/headless, o mesmo pode ser feito por meio de variáveis de ambiente e uma
reinicialização:```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>Definições da Base de Dados</strong></summary>

Exemplo com H2 incorporado:```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>Autenticação Externa (LDAP / JAAS)</strong></summary>

Autentique contra um servidor LDAP/Active Directory existente em vez de (ou em conjunto com) senhas
locais. Ative-o:```bash
export JAAS_MODULE=ldap-ol

Para mapear funções LDAP para perfis 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>Logon Único (SAML 2.0)</strong></summary>

Autentique-se contra um provedor de identidade empresarial — Microsoft Entra ID, Okta, ADFS ou qualquer
IdP SAML 2.0 — em vez de (ou em conjunto com) senhas locais ou LDAP. Um botão **Entrar com SSO**
aparece na página de login assim que configurado. Ative-o:```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>

Apenas necessário se o Entity ID registrado no lado do IdP não puder corresponder exatamente a `SAML_BASE_URL`:```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

Administradores são adicionados no primeiro login SSO e podem receber perfis de sistema.

**Nome de usuário exibido no Bastillion:** o SAML NameID se torna o nome de usuário. O Entra envia
`user.userprincipalname` por padrão, o que é adequado para membros regulares do tenant, mas gera um
UPN de convidado feio como `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com` para convidados B2B (qualquer pessoa
que entre com um e-mail pessoal ou externo adicionado como convidado). Para um nome de usuário mais limpo, vá para
o *Single sign-on* do Enterprise Application → SAML → *Attributes & Claims*, edite **Unique
User Identifier (Name ID)** e altere seu *Source attribute* de `user.userprincipalname`
para `user.mail`.

**Como o mapeamento de funções realmente funciona — mesmo mecanismo do LDAP acima:** `SAML_ROLE_ATTRIBUTE`
nomeia *qual* atributo de asserção carrega os grupos/funções do usuário; quaisquer *valores* que esse
atributo contenha em um determinado login são comparados, **por correspondência exata de texto**, com os nomes dos
Perfis que você criou em **Manage → Profiles**. Um valor que corresponde a um nome de perfil
atribui o usuário a ele; nada mais sobre a declaração importa. Portanto, um perfil do Bastillion deve ser
nomeado exatamente igual à string que a asserção envia — não há etapa de mapeamento separada
nem interface, os nomes apenas precisam coincidir.

Esta é a parte que mais frequentemente confunde as pessoas especificamente com o Entra ID: por padrão,
a declaração de grupo do Entra pode emitir cada grupo como seu **Object ID** (um GUID) em vez de seu nome
de exibição, a menos que a configuração de token do Enterprise Application seja explicitamente definida para emitir **nomes**
de grupo. Se seus perfis do Bastillion forem nomeados como `admins`/`everyone`, mas o Entra estiver
enviando GUIDs, nada jamais corresponderá. Verifique o valor real da declaração em uma asserção autêntica (ou
na configuração de token do Entra para o aplicativo) antes de presumir que o mapeamento está quebrado — geralmente é
isso, não um problema do lado do Bastillion. Três maneiras de corrigir, na ordem do que recomendamos:

1. **Use App Roles do Entra em vez de declarações de grupo (mais limpo).** No registro do aplicativo →
   App roles, defina funções com exatamente os valores que você deseja (`admins`, `everyone`, ...) e então
   atribua usuários/grupos a essas funções em *Users and groups* do Enterprise Application.
   Configure o token SAML para emitir a declaração `roles` e aponte `SAML_ROLE_ATTRIBUTE` para o
   URI dessa declaração em vez da declaração de grupos. Você escolhe a string exata que o Entra envia — sem problema
   de GUID algum, e é um modelo de autorização mais limpo do que reaproveitar grupos do AD de qualquer forma.
2. **Altere o atributo de origem da declaração de grupos.** Enterprise Application → Single sign-on →
   SAML → *Attributes & Claims* → edite a declaração Groups → há um menu suspenso *Source attribute*,
   normalmente padronizado para Group ID. Dependendo do seu tenant e se os grupos
   são somente na nuvem ou sincronizados do AD local, você pode conseguir alternar para `sAMAccountName`
   ou uma opção de nome de exibição — as escolhas exatas variam por tenant e versão do portal do Entra, então verifique
   o que é realmente oferecido em vez de presumir um rótulo específico.
3. **Ou não lute contra isso — nomeie o perfil do Bastillion conforme o que o Entra realmente envia.** Se
   o Entra insistir em enviar o GUID, crie um perfil do Bastillion literalmente nomeado com esse GUID.
   Mais feio, mas exige zero reconfiguração do lado do Entra.

Um usuário cujas declarações não correspondem a nenhum perfil do Bastillion é rejeitado no login (contas **Manager** são
a única exceção; elas não são limitadas por perfil) — exatamente como com LDAP, então
`DEFAULT_PROFILE_FOR_SAML` acima vale a pena definir pelo mesmo motivo que
`DEFAULT_PROFILE_FOR_LDAP`: uma rede de segurança enquanto você ainda está alinhando nomes de perfil com
os valores de declaração do seu IdP.

A verificação de senha de uso único do próprio Bastillion é ignorada para logins SSO — espera-se que o IdP
aplique sua própria política de MFA/Conditional Access. O cadastro inicial de OTP ainda é
oferecido para que usuários SAML tenham uma credencial de fallback local disponível se o SSO for desativado.

**Requisições assinadas e asserções criptografadas:** o Bastillion gera seu próprio certificado de assinatura SAML
automaticamente (autoassinado, da mesma forma que gera seu certificado TLS) na
primeira vez em que é necessário, e assina cada AuthnRequest de saída com ele a partir de então — sem
configuração necessária, e inofensivo mesmo se seu IdP não o verificar. Busque
`https://bastillion.example.com/saml/metadata` para obter esse certificado no formato padrão de
metadados SP e entregue-o ao administrador do seu IdP se eles precisarem verificar as requisições assinadas
do Bastillion, ou criptografar asserções para o Bastillion — a maioria dos IdPs pode importar uma URL de
metadados SP diretamente em vez de colar um certificado bruto. Se preferir usar um par de chaves real (por exemplo,
emitido por CA) em vez do gerado automaticamente, aponte `SAML_SP_KEYSTORE_PATH`/
`SAML_SP_KEYSTORE_PASSWORD` para um keystore PKCS12 que o contenha. Para *exigir* asserções
criptografadas (desativado por padrão — só ative isso quando seu IdP estiver realmente configurado para
criptografar para o certificado do Bastillion, ou todo login começará a falhar):```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

Existe também um registro de auditoria baseado em arquivo, desabilitado por padrão. Ative-o no **log4j2.xml** removendo os comentários de:
- `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>Migrando da v4</strong></summary>

Atualizando a partir de uma instalação antiga do Bastillion v4 e quer manter seus usuários, sistemas, perfis,
scripts e (o mais importante) o par de chaves SSH existente da aplicação em vez de começar
do zero? `tools/migrate/` possui uma ferramenta de migração independente exatamente para isso — ela exporta cada
tabela do banco de dados H2 antigo (descriptografando as colunas criptografadas no nível da aplicação com o
keystore da instância ANTIGA) para um arquivo JSON e, em seguida, importa-o em uma nova instância v5 (recriptografando
com o keystore da instância NOVA). Os usuários existentes podem fazer login com suas senhas atuais
imediatamente após — sem redefinições forçadas.```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