Skip to main content

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.

Guida Wiki — 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 file:

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 virtual host simile:

bao.example.com {
    reverse_proxy 127.0.0.1:8200
}

Poi 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
Key shares 5
Key threshold 3

Significato:

  • vengono generate 5 unseal keys;
  • ne servono 3 per sbloccare OpenBao;
  • nessuna singola persona può sbloccare il vault da sola.

Lasciare non configurate le sezioni PGP, salvo policy aziendale specifica.

Cliccare:

Initialize

10. Conservazione delle chiavi

Dopo 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 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 / emergenza

11. Unseal di OpenBao

Dopo l’inizializzazione OpenBao rimane in stato:

sealed

Dalla Web UI:

  1. inserire una prima Unseal Key;
  2. cliccare Unseal;
  3. inserire una seconda Unseal Key;
  4. cliccare Unseal;
  5. inserire una terza Unseal Key;
  6. cliccare Unseal.

Con configurazione 5 / 3, servono 3 chiavi diverse.

In alternativa 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

Verifica stato:

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 password 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:

  1. accedere alla Web UI;
  2. aprire il secret engine secret;
  3. entrare in dev;
  4. creare un nuovo secret, ad esempio:
app1
  1. aggiungere coppie chiave/valore:
DB_USER = app1_user
DB_PASSWORD = password
API_KEY = valore
  1. salvare.

24. Messa in sicurezza post-installazione

Dopo aver creato l’utente admin:

  1. fare logout dalla UI;
  2. accedere con l’utente admin;
  3. verificare che l’utente admin funzioni;
  4. conservare il root token in cassaforte/password manager;
  5. 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:

  1. aprire:
https://bao.example.com
  1. inserire 3 delle 5 unseal keys;
  2. verificare login;
  3. 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.

Login root token non funziona

Possibili 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 secret sia sotto:

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

Fare unseal con 3 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'
Back to top