Installazione

Deploy

Componenti

Utenti / Dev
    |
    | HTTPS
    v
Caddy esistente
    |
    | reverse_proxy
    v
OpenBao container
    |
    v
Volume Docker persistente / directory bind mount

sudo mkdir -p /opt/openbao/{config,data,logs}
sudo chown -R 100:1000 /opt/openbao
cd /opt/openbao

/opt/openbao/
├── docker-compose.yml
├── config/
│   └── openbao.hcl
├── data/
└── logs/

sudo nano /opt/openbao/config/openbao.hcl

Contenuto:

ui = true

disable_mlock = true

storage "raft" {
  path    = "/openbao/data"
  node_id = "openbao-01"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

api_addr = "https://bao.example.com"
cluster_addr = "http://openbao:8201"

log_level = "info"

sudo nano /opt/openbao/docker-compose.yml

Contenuto:

services:
  openbao:
    image: ghcr.io/openbao/openbao:latest
    container_name: openbao
    restart: unless-stopped

    command: server -config=/openbao/config/openbao.hcl

    cap_add:
      - IPC_LOCK

    volumes:
      - /opt/openbao/config:/openbao/config:ro
      - /opt/openbao/data:/openbao/data
      - /opt/openbao/logs:/openbao/logs

    ports:
      - "127.0.0.1:8200:8200"

    environment:
      BAO_ADDR: "http://127.0.0.1:8200"

    networks:
      - openbao-net

    security_opt:
      - no-new-privileges:true

    mem_swappiness: 0

networks:
  openbao-net:
    name: openbao-net

Primo avvio

Questa schermata è la fase di inizializzazione di OpenBao.

Qui OpenBao ti chiede di creare le root keys / unseal keys, cioè le chiavi necessarie per sbloccare il vault in caso di riavvio, manutenzione o emergenza.

---

ValoriGuida consigliatiWiki — Installazione e configurazione iniziale OpenBao con Docker Compose e Caddy

---

1. Obiettivo

Questa guida descrive come installare e configurare OpenBao in azienda con:

deploy tramite Docker Compose; reverse proxy Caddy già esistente; accesso via Web UI; autenticazione locale userpass; secret engine KV v2; nessuna integrazione LDAP; nessuna configurazione HA; backup e disaster recovery gestiti a livello VM.

OpenBao verrà usato per permettere ai team di sviluppo di salvare e consultare secret aziendali tramite interfaccia web.

---

2. Architettura prevista

Utente / Browser
      |
      | HTTPS
      v
Caddy reverse proxy esistente
      |
      | HTTP interno
      v
OpenBao container
      |
      v
Volume Docker persistente

Esempio endpoint:

https://bao.example.com

---

3. Prerequisiti

Sulla VM devono essere presenti:

Docker; Docker Compose plugin; Caddy già installato e operativo; DNS configurato verso la VM; porta HTTPS esposta tramite Caddy; backup e disaster recovery già attivi sulla VM.

Verifica Docker:

docker --version
docker compose version

---

4. Directory di lavoro

Creare una directory dedicata:

sudo mkdir -p /opt/openbao
cd /opt/openbao

Impostare permessi adeguati:

sudo chown -R root:root /opt/openbao
sudo chmod 750 /opt/openbao

---

5. File Docker Compose

Creare il tuofile:

scenario

sudo nano /opt/openbao/docker-compose.yml

Contenuto consigliato:

services:
  openbao:
    image: openbao/openbao:latest
    container_name: openbao
    restart: unless-stopped
    command: server -config=/etc/openbao/openbao.hcl
    cap_add:
      - IPC_LOCK
    volumes:
      - ./config:/etc/openbao
      - ./data:/openbao/data
    environment:
      BAO_ADDR: "http://127.0.0.1:8200"
      BAO_API_ADDR: "https://bao.example.com"
    ports:
      - "127.0.0.1:8200:8200"

Sostituire:

bao.example.com

con il dominio reale.

---

6. File di configurazione OpenBao

Creare la directory di configurazione:

sudo mkdir -p /opt/openbao/config /opt/openbao/data

Creare il file:

sudo nano /opt/openbao/config/openbao.hcl

Contenuto:

ui = true

disable_mlock = true

storage "file" {
  path = "/openbao/data"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

api_addr = "https://bao.example.com"

Sostituire:

bao.example.com

con il FQDN reale esposto da Caddy.

Nota: TLS viene terminato da Caddy. Per questo motivo OpenBao ascolta in HTTP solo su localhost tramite Docker port binding.

---

7. Avvio del container

Da /opt/openbao:

sudo docker compose up -d

Verifica:

sudo docker ps
sudo docker logs -f openbao

Il servizio dovrebbe essere raggiungibile localmente su:

http://127.0.0.1:8200

---

8. Configurazione Caddy

Sul reverse proxy Caddy esistente, aggiungere un deploymentvirtual aziendalehost semplice,simile:

single-node,

bao.example.com senza{
    HAreverse_proxy e127.0.0.1:8200
senza}
auto-unseal,

ti

Poi consiglio:ricaricare Caddy:

sudo systemctl reload caddy

Verificare l’accesso da browser:

https://bao.example.com

---

9. Inizializzazione OpenBao

Alla prima apertura della Web UI comparirà la schermata di inizializzazione.

Valori consigliati:

Campo	Valore consigliato
Key shares	5
Key threshold	3

Quindi:

Key shares: 5
Key threshold: 3

Significa:Significato:

• OpenBaovengono genereràgenerate 5 keyunseal shareskeys.;
• Nene servirannoservono almeno 3 per faresbloccare unseal.OpenBao;
• Nessunanessuna singola persona potràpuò sbloccare OpenBaoil vault da sola, se distribuite correttamente.sola.

---

Lasciare

Cosanon significaconfigurate inle pratica

sezioni PGP, salvo policy aziendale specifica.

Con 5 / 3:Cliccare:

Totale chiavi generate: 5
Chiavi necessarie per unseal: 3Initialize

---

10. Conservazione delle chiavi

EsempioDopo l’inizializzazione verranno mostrati:

Unseal Key 1 Unseal Key 2 Unseal Key 3 Unseal Key 4 Unseal Key 5 Initial Root Token

Questi dati sono estremamente sensibili.

Non salvarli in:

email; chat; repository Git; ticket; file non cifrati; documenti condivisi senza protezione.

Salvarli invece in:

password manager aziendale; cassaforte digitale; supporto offline cifrato; procedura di distribuzione:emergenza cartacea sigillata.

Distribuzione consigliata:

Chiave	Custode
Unseal Key 1	Responsabile IT
Unseal Key 2	DevOps Lead
Unseal Key 3	Security Officer
Unseal Key 4	CTO / IT Manager
Unseal Key 5	Cassaforte digitale aziendale / emergenza

Per

---

sbloccare

11. OpenBao dopo un riavvio serviranno 3Unseal di queste 5 chiavi.

Posso usare valori più semplici?

Sì, ma valuta il rischio.

Opzione più semplice

Key shares: 3
Key threshold: 2

Pro:

Più semplice da gestire. Bastano 2 persone per fare unseal.

Contro:

Meno resilienza organizzativa. Se perdi 2 chiavi su 3, non puoi più sbloccare OpenBao.

Opzione ultra-semplice, non consigliata in azienda

Key shares: 1
Key threshold: 1

Pro:

Facilissima.

Contro:

Una sola persona/chiave può sbloccare tutto. Se perdi quella chiave, sei bloccato. Non adatta a un contesto aziendale.

---

Cosa fare con PGP?

Nella schermata vedo due sezioni:

Encrypt output with PGP Encrypt root token with PGP

Per il setup iniziale ti consiglio:

Non usare PGP, a meno che abbiate già una procedura PGP aziendale consolidata.

Quindi puoi lasciare chiuse/non configurate queste sezioni.

Il motivo è pratico: PGP aumenta la sicurezza dell’output, ma se non avete già gestione chiavi PGP, custodi, revoca, backup delle private key e procedure documentate, rischia di complicare il recovery.

---

Cosa succede dopo aver cliccato Initialize

Dopo Initialize, OpenBao mostrerà qualcosa tipo:

Unseal Key 1: ...
Unseal Key 2: ...
Unseal Key 3: ...
Unseal Key 4: ...
Unseal Key 5: ...

Initial Root Token: ...

Questi dati sono estremamente sensibili.

---

Cosa devi salvare subito

Devi salvare:

Le 5 unseal keys. L’initial root token.

Non salvarle in:

chat; email; file di testo sul desktop; repository Git; ticket Jira; documenti condivisi senza cifratura.

Salvale invece in:

password manager aziendale; cassaforte digitale; vault separato; supporto offline cifrato; procedura cartacea sigillata, se usate policy di emergenza.

---

Procedura consigliata

Inserisci:

Key shares: 5
Key threshold: 3

Lascia non configurate le sezioni PGP, salvo policy aziendale esistente.

Clicca:

Initialize

Salva immediatamente le 5 unseal keys.

Salva immediatamente l’initial root token.

Distribuisci le unseal keys a custodi diversi.

Usa il root token solo per:

configurazione iniziale; creazione utenti admin; recovery.

Dopo aver creato un utente admin dedicato, conserva il root token e non usarlo nel lavoro quotidiano.

---

Subito dopo: unseal

Dopo l’inizializzazione OpenBao saràrimane ancorain stato:

sealed

Dalla Web UI:

inserire una prima Unseal Key; cliccare sealedUnseal; inserire una seconda Unseal Key; cliccare Unseal; inserire una terza Unseal Key; cliccare Unseal.

Con configurazione 5 / 3, servono 3 chiavi diverse.

DovraiIn inserire 3 delle 5 chiavi per sbloccarlo.

Puoi farlo dalla UI oppurealternativa da CLI:

sudo docker exec -it openbao bao operator unseal
sudo docker exec -it openbao bao operator unseal
sudo docker exec -it openbao bao operator unseal

OgniVerifica comandostato:

richiederà

sudo docker exec -it openbao bao status

Output atteso:

Sealed: false

---

12. Login iniziale

Una volta effettuato l’unseal, accedere alla Web UI.

Metodo:

Token

Token:

Initial Root Token

Il root token deve essere usato solo per la configurazione iniziale e per emergenza.

---

13. Configurazione iniziale via CLI

Entrare nel container:

sudo docker exec -it openbao sh

Impostare l’indirizzo locale:

export BAO_ADDR='http://127.0.0.1:8200'

Eseguire login:

bao login

Incollare l’Initial Root Token.

---

14. Abilitare il secret engine KV v2

Abilitare il motore KV v2 sul path secret:

bao secrets enable -path=secret kv-v2

Verificare:

bao secrets list

---

15. Creazione policy admin

Creare il file policy:

cat > /tmp/admin-policy.hcl <<'EOF'
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

Caricare la policy:

bao policy write admin /tmp/admin-policy.hcl

---

16. Creazione policy dev

Questa policy consente ai dev di gestire secret sotto:

secret/dev/

Creare il file:

cat > /tmp/dev-policy.hcl <<'EOF'
path "secret/data/dev/*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "secret/metadata/dev/*" {
  capabilities = ["list", "read", "delete"]
}
EOF

Caricare la policy:

bao policy write dev /tmp/dev-policy.hcl

---

17. Abilitare autenticazione username/password

Abilitare il metodo userpass:

bao auth enable userpass

---

18. Creazione utente admin

Creare un utente amministrativo personale o tecnico:

bao write auth/userpass/users/admin \
  password='CAMBIA_QUESTA_PASSWORD_ADMIN' \
  policies='admin'

Usare una chiavepassword diversa.robusta e salvarla nel password manager aziendale.

---

19. Creazione utenti dev

Esempio:

bao write auth/userpass/users/mario.rossi \
  password='CAMBIA_QUESTA_PASSWORD_DEV' \
  policies='dev'

Per altri utenti:

bao write auth/userpass/users/nome.cognome \
  password='PASSWORD_TEMPORANEA' \
  policies='dev'

---

20. Accesso dei dev dalla Web UI

I dev devono accedere a:

https://bao.example.com

Metodo di login:

Username

oppure:

Userpass

a seconda di come viene mostrato nella UI.

Credenziali:

Username: nome.cognome
Password: password assegnata

---

21. Percorso per i secret dei dev

I dev devono salvare i secret sotto:

secret/dev/

Esempi:

secret/dev/app1
secret/dev/app2
secret/dev/backend
secret/dev/frontend
secret/dev/shared

Esempio struttura:

secret/
└── dev/
    ├── app1
    │   ├── DB_USER
    │   ├── DB_PASSWORD
    │   └── API_KEY
    ├── backend
    │   ├── REDIS_URL
    │   └── JWT_SECRET
    └── shared
        └── SENTRY_DSN

---

22. Test inserimento secret da CLI

Esempio:

bao kv put secret/dev/app1 \
  DB_USER='app1_user' \
  DB_PASSWORD='password-di-test' \
  API_KEY='api-key-di-test'

Lettura:

bao kv get secret/dev/app1

---

23. Test da Web UI

Con utente dev:

accedere alla Web UI; aprire il secret engine secret; entrare in dev; creare un nuovo secret, ad esempio:

app1

aggiungere coppie chiave/valore:

DB_USER = app1_user
DB_PASSWORD = password
API_KEY = valore

salvare.

---

24. Messa in sicurezza post-installazione

Dopo aver creato l’utente admin:

fare logout dalla UI; accedere con l’utente admin; verificare che l’utente admin funzioni; conservare il root token in cassaforte/password manager; non usare più il root token per operazioni quotidiane.

---

25. Comandi utili

Stato OpenBao

sudo docker exec -it openbao bao status

Log container

sudo docker logs -f openbao

Restart container

cd /opt/openbao
sudo docker compose restart

Stop

cd /opt/openbao
sudo docker compose down

Start

cd /opt/openbao
sudo docker compose up -d

Lista secret engine

sudo docker exec -it openbao bao secrets list

Lista auth method

sudo docker exec -it openbao bao auth list

---

26. Procedura dopo riavvio VM

Dopo un riavvio della VM, OpenBao potrebbe tornare in stato:

sealed

Procedura:

aprire:

https://bao.example.com

inserire 3 delle 5 unseal keys; verificare login; controllare lo stato:

sudo docker exec -it openbao bao status

Output atteso:

Sealed: false

---

27. Troubleshooting

UI non raggiungibile

Verificare container:

sudo docker ps
sudo docker logs openbao

Verificare porta locale:

curl http://127.0.0.1:8200/ui/

Verificare Caddy:

sudo systemctl status caddy
sudo journalctl -u caddy -f

---

Errore Caddy / reverse proxy

Verificare che in docker-compose.yml sia presente:

ports:
  - "127.0.0.1:8200:8200"

Verificare che nel Caddyfile ci sia:

bao.example.com {
    reverse_proxy 127.0.0.1:8200
}

Ricaricare:

sudo systemctl reload caddy

---

OpenBao sealed

Verificare:

sudo docker exec -it openbao bao status

Se:

Sealed: true

eseguire unseal con 3 chiavi.

---

RaccomandazioneLogin finaleroot token non funziona

PerPossibili cause:

token copiato male; OpenBao ancora sealed; token revocato; si sta usando una unseal key al posto del root token.

Verificare stato:

sudo docker exec -it openbao bao status

---

I dev non vedono i secret

Verificare policy:

bao policy read dev

Verificare utente:

bao read auth/userpass/users/mario.rossi

Verificare che il tuosecret casosia aziendalesotto:

scegli:

secret/dev/

---

28. Procedura rapida completa

Da usare solo come checklist operativa.

cd /opt/openbao
sudo docker compose up -d

Inizializzare da UI:

Key shares: 5
Key threshold: 3

eFare lasciaunseal PGPcon disattivato,3 salvo che abbiate già una gestione PGP interna ben definita.chiavi.

Poi:

sudo docker exec -it openbao sh

export BAO_ADDR='http://127.0.0.1:8200'
bao login

Configurazione:

bao secrets enable -path=secret kv-v2

cat > /tmp/admin-policy.hcl <<'EOF'
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

bao policy write admin /tmp/admin-policy.hcl

cat > /tmp/dev-policy.hcl <<'EOF'
path "secret/data/dev/*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "secret/metadata/dev/*" {
  capabilities = ["list", "read", "delete"]
}
EOF

bao policy write dev /tmp/dev-policy.hcl

bao auth enable userpass

bao write auth/userpass/users/admin \
  password='CAMBIA_QUESTA_PASSWORD_ADMIN' \
  policies='admin'

bao write auth/userpass/users/dev1 \
  password='CAMBIA_QUESTA_PASSWORD_DEV' \
  policies='dev'