64 lines
2.2 KiB
Markdown
64 lines
2.2 KiB
Markdown
# `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.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
CLIENT["Installazione ThothII"] -->|"X-API-Key"| NGINX["Nginx"]
|
|
NGINX --> AUTH["dwh-auth\nUnix socket"]
|
|
AUTH --> REGISTRY["Registro chiavi\nactive e revoked"]
|
|
AUTH -->|"authorized"| REST["DWH REST"]
|
|
```
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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.key
|
|
```
|
|
|
|
Deliver 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:
|
|
|
|
```bash
|
|
sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
|
|
--key-id PUBLIC_KEY_ID \
|
|
--reason scheduled-rotation
|
|
```
|
|
|
|
Revocation 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`.
|