137 lines
6.6 KiB
Markdown
137 lines
6.6 KiB
Markdown
# `dwh-auth`: guida server
|
|
|
|
`dwh-auth` autentica la route REST `/dwh/` con una chiave per installazione. È un componente Linux
|
|
opzionale e server-side: usa `systemd`, non `tht` né Docker Compose, non legge risultati clinici e
|
|
non si collega a PostgreSQL. La chiave serve solo a `rest_api`; `postgres_direct` e `ssh_tunnel`
|
|
non la usano.
|
|
|
|
## Prerequisiti e confini
|
|
|
|
- Usare un checkout revisionato, Docker per la build e un operatore autorizzato sul server DWH.
|
|
- Una chiave identifica un'installazione, non una persona. L'`installation-id` è unico, non
|
|
personale e senza dati clinici.
|
|
- Chiavi, digest, file di consegna e backup restano in file protetti: mai Git, argv, variabili
|
|
d'ambiente, log, JSON pubblico o evidenze.
|
|
- Preparare backup e rollback prima di Nginx. Installare il servizio non autorizza una modifica
|
|
della route pubblica.
|
|
|
|
## Percorsi, owner e mode
|
|
|
|
| Oggetto | Percorso | Owner e mode |
|
|
| --- | --- | --- |
|
|
| Binario | `/usr/local/sbin/dwh-auth` | `root:root`, `0755` |
|
|
| Unit | `/etc/systemd/system/dwh-auth.service` | `root:root`, `0644` |
|
|
| Tmpfiles | `/usr/lib/tmpfiles.d/dwh-auth.conf` | `root:root`, `0644` |
|
|
| Registro, `active`, `revoked` | `/var/lib/dwh-auth/` | `root:dwh-auth`, `2750` |
|
|
| Lock | `/var/lib/dwh-auth/.writer.lock` | `root:dwh-auth`, `0640` |
|
|
| Record | `/var/lib/dwh-auth/{active,revoked}/<public-key-id>.json` | `root:dwh-auth`, `0640` |
|
|
| Socket runtime | `/run/dwh-auth/verify.sock` | `dwh-auth:www-data`, `0660` |
|
|
| Consegne e backup | `/root/dwh-auth-provision/` | directory `root:root` `0700`, file `0600` |
|
|
|
|
Il record conserva un digest interno (`secret_sha256`) e metadati, mai la chiave in chiaro. Non
|
|
leggere, stampare, calcolare o mettere quel digest in una prova operativa.
|
|
|
|
## Build, installazione e avvio
|
|
|
|
Costruire dal commit congelato e registrare solo checksum del binario e SHA sorgente:
|
|
|
|
```bash
|
|
cd /srv/thothii/app
|
|
bash scripts/build-dwh-auth.sh --output /tmp/dwh-auth-release
|
|
sha256sum /tmp/dwh-auth-release/dwh-auth-linux-amd64
|
|
```
|
|
|
|
Scegliere l'architettura corretta. Il template PSD usa il gruppo Nginx `www-data`; confermarlo
|
|
prima dell'installazione su un host diverso.
|
|
|
|
```bash
|
|
sudo groupadd --system dwh-auth
|
|
sudo useradd --system --no-create-home --shell /usr/sbin/nologin --gid dwh-auth dwh-auth
|
|
sudo install -o root -g root -m 0755 /tmp/dwh-auth-release/dwh-auth-linux-amd64 /usr/local/sbin/dwh-auth
|
|
sudo install -o root -g root -m 0644 deploy/dwh-auth/dwh-auth.service /etc/systemd/system/dwh-auth.service
|
|
sudo install -o root -g root -m 0644 deploy/dwh-auth/dwh-auth.tmpfiles.conf /usr/lib/tmpfiles.d/dwh-auth.conf
|
|
sudo install -d -o root -g root -m 0700 /root/dwh-auth-provision
|
|
sudo systemd-tmpfiles --create /usr/lib/tmpfiles.d/dwh-auth.conf
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth check
|
|
sudo systemd-analyze verify /etc/systemd/system/dwh-auth.service
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now dwh-auth
|
|
sudo systemctl status dwh-auth --no-pager
|
|
```
|
|
|
|
Controllare i mode con `stat`. Il servizio apre il registro in sola lettura e crea solo il socket.
|
|
Non creare JSON, lock o socket a mano: oggetti insicuri devono fallire chiusi.
|
|
|
|
## Check, elenco e stato
|
|
|
|
Usare sempre un root assoluto. Questi comandi espongono solo ID pubblici, stato, date e scadenza:
|
|
|
|
```bash
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth check
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key list --json
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key status --key-id <public-key-id> --json
|
|
```
|
|
|
|
Un errore di integrità, permessi, symlink o JSON malformato richiede ripristino da backup protetto,
|
|
non una correzione manuale del record.
|
|
|
|
## Creazione, consegna, scadenza e revoca
|
|
|
|
Il comando crea la chiave una volta in un nuovo file assoluto `0600`; stdout contiene solo ID
|
|
pubblico, installazione e percorso. Il file di output non deve esistere.
|
|
|
|
```bash
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key create \
|
|
--installation-id <installation-id> \
|
|
--description <metadato-non-segreto> \
|
|
--output /root/dwh-auth-provision/<installation-id>-<generation>.key
|
|
```
|
|
|
|
Aggiungere `--expires-at <RFC3339-UTC>` solo se la policy impone una scadenza; il default è nessuna
|
|
scadenza. Consegnare il file solo con vault aziendale, secret manager, MDM o trasferimento
|
|
autenticato ristretto. Mai email, chat, ticket, `cat` o copia-incolla. Il client conferma ID
|
|
pubblico e ping, poi il materiale temporaneo viene rimosso secondo policy.
|
|
|
|
L'import legacy è temporaneo PSD: il file sorgente è già `root:root` `0600` e non viene mai letto o
|
|
stampato dall'operatore.
|
|
|
|
```bash
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key import \
|
|
--legacy-raw --installation-id legacy-shared \
|
|
--from-file /root/dwh-auth-provision/legacy-shared.key
|
|
```
|
|
|
|
Per rotare: creare seconda generazione, consegnarla, configurarla e provare `/rpc/ping`; confermare
|
|
l'ID pubblico; attendere l'osservazione; poi revocare la precedente e provare nuova=successo,
|
|
precedente=401.
|
|
|
|
```bash
|
|
sudo /usr/local/sbin/dwh-auth --registry-root /var/lib/dwh-auth key revoke \
|
|
--key-id <previous-public-key-id> --reason <non-secret-reason>
|
|
```
|
|
|
|
La revoca non è annullabile e un ID revocato non si ricrea.
|
|
|
|
## Backup, rollback e disinstallazione
|
|
|
|
Prima di mutare, creare un archivio cifrato e protetto del registro e copie protette delle sole
|
|
configurazioni coinvolte. L'archivio contiene digest, quindi è riservato: evidenza ammessa solo
|
|
percorso, owner, mode, timestamp e checksum dell'archivio. Il rollback dual-key ripristina la route
|
|
e il servizio revisionati, esegue `nginx -t` e fa reload solo autorizzato; non ripristina chiavi
|
|
revocate, PostgreSQL, sessioni legacy, indici Qdrant o cache Ollama.
|
|
|
|
La disinstallazione richiede autorizzazione esplicita, client REST migrati/revocati e rollback non
|
|
più necessario. Solo allora disabilitare l'unità; conservare registro e backup fino alla retention
|
|
approvata. Non inserire `dwh-auth` in Compose o in `tht start`/`tht stop`.
|
|
|
|
## Troubleshooting
|
|
|
|
| Sintomo | Interpretazione e azione |
|
|
| --- | --- |
|
|
| `401` | Chiave assente, malformata, sconosciuta, scaduta, revocata o errata. Verificare trasporto, ID pubblico e consegna; non cercare dettagli nel messaggio. |
|
|
| `503` | Servizio, socket o registro non disponibile/sicuro. Controllare `systemctl`, socket, mode e `check`; ripristinare il backup approvato. |
|
|
| `check` fallisce | Integrità del registro non valida. Fermare le scritture, preservare stato e ripristinare; non editare JSON. |
|
|
| TLS fallisce | CA o SAN non validi. Seguire [TLS](dwh-auth-tls.md), senza bypass. |
|
|
|
|
Per il rollout PSD con i due gate separati vedere il [runbook PSD](../operations/psd-dwh-auth-rollout.md).
|