Sicurezza e Autenticazione

Sicurezza e Autenticazione

PgArachne si affida interamente al sistema di permessi di PostgreSQL. Non reinventa le Liste di Controllo degli Accessi (ACL). PgArachne supporta quattro metodi di autenticazione. I metodi 1–3 usano SET LOCAL ROLE per cambiare identità; il metodo 4 (credenziali dirette) si connette direttamente come l’utente, quindi non è necessario alcun cambio di ruolo.

1. Login Interattivo (JWT)

Gli utenti si autenticano utilizzando il loro reale nome utente e password PostgreSQL tramite il metodo JSON-RPC get_jwt. In caso di successo, ricevono un JWT di breve durata. Le richieste successive trasportano questo token nell’header Authorization: Bearer <token>, e PgArachne cambia il ruolo attivo in quell’utente per la durata di ogni richiesta.

2. Account di Servizio (Token API)

Per sistemi automatizzati o script, puoi utilizzare token API a lunga durata.

• I token sono memorizzati nella tabella pgarachne.api_tokens.
• Ogni token è mappato a un utente/ruolo database specifico.
• Invia il token tramite l’header Authorization: Bearer <token>.

La creazione di token API richiede pgarachne_admin. Usa pgarachne.add_api_token(...) con un ruolo membro di pgarachne_admin.

3. Identity provider esterno (JWT personalizzato)

Se autentichi gli utenti fuori da PgArachne (ad esempio con un servizio di autenticazione esterno), puoi generare lì i JWT e inviarli direttamente a PgArachne.

• Formato header: Authorization: Bearer <jwt>.
• Firma: solo HMAC (HS256/HS384/HS512) con lo stesso JWT_SECRET configurato in PgArachne.
• Claim obbligatori: db_role (stringa non vuota) e db_name (stringa che deve corrispondere a /api/:database).
• Claim consigliato: exp (timestamp Unix) per la scadenza del token.

Esempio minimo di payload:

{
  "db_role": "demo_user",
  "db_name": "my_database",
  "exp": 1767225600
}

Importante: gli algoritmi JWT asimmetrici (ad esempio RS256/ES256) non sono accettati dall’implementazione attuale del server.

4. Credenziali dirette del database (Basic Auth)

L’opzione più semplice: invia il nome utente e la password PostgreSQL con ogni richiesta usando la normale autenticazione HTTP Basic. PgArachne apre un pool di connessioni dedicato, autenticato direttamente come quell’utente — SET LOCAL ROLE non viene eseguito.

Authorization: Basic <base64(username:password)>

Esempio con curl:

curl -X POST http://localhost:8080/db/my_database/jsonrpc \
  -u demo_user:user_password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"api.hello_world","params":{},"id":1}'

Differenze principali rispetto ai metodi basati su token:

• Non è richiesto alcun GRANT demo_user TO pgarachne — PgArachne non cambia ruolo.
• La Row-Level Security di PostgreSQL e i permessi GRANT vengono applicati normalmente perché la connessione viene eseguita come l’utente reale.
• I pool di connessioni sono mantenuti per utente per efficienza, con una durata massima di 5 minuti. Dopo un cambio di password, le vecchie connessioni scadono entro quella finestra temporale.
• Perché le chiavi di idempotenza funzionino con le credenziali dirette, concedi all’utente EXECUTE ON FUNCTION pgarachne.save_idempotency_key(text).

-- Richiesto solo per l'autenticazione JWT / a token API:
GRANT demo_user TO pgarachne;

Confronto dei metodi di autenticazione

Vedi anche

• Configurazione
• Codici di Errore