Bezpieczeństwo i uwierzytelnianie

Bezpieczeństwo i uwierzytelnianie

PgArachne opiera się całkowicie na systemie uprawnień PostgreSQL. Nie tworzy własnych list kontroli dostępu (ACL). PgArachne wspiera cztery metody uwierzytelniania. Metody 1–3 wykorzystują SET LOCAL ROLE do przełączania tożsamości; metoda 4 (bezpośrednie dane logowania) łączy się bezpośrednio jako dany użytkownik, więc przełączanie roli nie jest potrzebne.

1. Logowanie interaktywne (JWT)

Użytkownicy uwierzytelniają się za pomocą swojej rzeczywistej nazwy użytkownika i hasła PostgreSQL poprzez metodę JSON-RPC get_jwt. Jeśli logowanie powiedzie się, otrzymują krótkotrwały JWT. Kolejne żądania przekazują ten token w nagłówku Authorization: Bearer <token>, a PgArachne przełącza aktywną rolę na tego użytkownika na czas trwania każdego żądania.

2. Konta serwisowe (tokeny API)

Dla systemów automatycznych lub skryptów zalecane są długoterminowe tokeny API.

• Tokeny są przechowywane w tabeli pgarachne.api_tokens.
• Każdy token jest przypisany do konkretnej roli w bazie danych.
• Token wysyła się w nagłówku Authorization: Bearer <token>.

Generowanie tokenów API wymaga roli pgarachne_admin. Użyj pgarachne.add_api_token(...) z rolą, która jest członkiem pgarachne_admin.

3. Zewnętrzny dostawca identyfikacji (własny JWT)

Jeśli użytkownicy są uwierzytelniani poza PgArachne (na przykład przez zewnętrzną usługę uwierzytelniania), możesz generować tam JWT i wysyłać je bezpośrednio do PgArachne.

• Format nagłówka: Authorization: Bearer <jwt>.
• Podpisywanie: tylko HMAC (HS256 / HS384 / HS512) z użyciem tego samego JWT_SECRET skonfigurowanego w PgArachne.
• Wymagane claimy: db_role (ciąg znaków, niepusty) oraz db_name (ciąg znaków, musi odpowiadać segmentowi ścieżki :database).
• Zalecany claim: exp (znacznik czasu Unix) do określenia wygaśnięcia tokenu.

Minimalny przykład payloadu:

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

Uwaga: asymetryczne algorytmy JWT (np. RS256 / ES256) nie są wspierane.

4. Bezpośrednie dane logowania do bazy danych (Basic Auth)

Najprostsza opcja: wysyłaj nazwę użytkownika i hasło PostgreSQL z każdym żądaniem, używając standardowego HTTP Basic Authentication. PgArachne otwiera dedykowany pool połączeń uwierzytelniony bezpośrednio jako ten użytkownik — SET LOCAL ROLE nie jest wykonywane.

Authorization: Basic <base64(username:password)>

Przykład z 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}'

Kluczowe różnice względem metod opartych na tokenach:

• GRANT demo_user TO pgarachne nie jest wymagane — PgArachne nie przełącza ról.
• Row-Level Security PostgreSQL oraz uprawnienia GRANT są wymuszane jak zwykle, ponieważ połączenie działa jako rzeczywisty użytkownik.
• Poole połączeń są utrzymywane osobno dla każdego użytkownika, z maksymalnym czasem życia 5 minut. Po zmianie hasła stare połączenia wygasają w tym okresie.
• Aby klucze idempotencji działały z bezpośrednimi danymi logowania, przyznaj użytkownikowi uprawnienie EXECUTE ON FUNCTION pgarachne.save_idempotency_key(text).

-- Wymagane tylko dla uwierzytelniania JWT / tokenem API:
GRANT demo_user TO pgarachne;

Porównanie metod uwierzytelniania

Zobacz także

• Konfiguracja
• Kody błędów