dwh-auth: server guide¶
dwh-auth protects the REST /dwh/ route with a separate key for each ThothII installation.
It runs as a separate Linux service, does not read DWH data, and does not connect directly to
PostgreSQL.
Security boundaries¶
- A key identifies an installation, not a person.
- Keys and backups stay in protected files and never enter Git, logs, arguments, or public JSON.
- The registry stores digests and metadata, never the key in plaintext.
- The REST route must be exposed only through verified TLS.
Installation¶
Il servizio usa questi percorsi:
| Oggetto | Percorso |
|---|---|
| Binario | /usr/local/sbin/dwh-auth |
| Unit systemd | /etc/systemd/system/dwh-auth.service |
| Registro | /var/lib/dwh-auth/ |
| Socket | /run/dwh-auth/verify.sock |
| Consegne protette | /root/dwh-auth-provision/ |
Install the binary and unit with root ownership, create the dwh-auth service user, and enable
the unit with systemctl enable --now dwh-auth. The socket must be accessible to Nginx's group.
Creating and revoking keys¶
Esempio per l'installazione ACME Limited:
sudo dwh-auth --registry-root /var/lib/dwh-auth key create \
--installation-id acme-factory-primary \
--description acme-factory-primary \
--output /root/dwh-auth-provision/acme-factory-primary.keyDeliver the file through an enterprise vault or an authenticated channel. To rotate a key, create a new one, distribute it, update the client, and revoke the old one using its public ID:
sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
--key-id PUBLIC_KEY_ID \
--reason scheduled-rotationRevocation is permanent. Keep encrypted registry backups before every mutation.
Nginx integration¶
Nginx forwards the key to the dwh-auth socket. Only an authorized response allows the request
to reach DWH REST. Missing, unknown, expired, or revoked keys receive 401; an unavailable
service or registry produces 503.