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 35

    Significato:

    • vengono generate 5 unseal keys;
    • ne servono 35 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'