Безпека та автентифікація

Безпека та автентифікація

PgArachne повністю покладається на систему прав доступу PostgreSQL. Він не винаходить власні списки контролю доступу (ACL). PgArachne підтримує чотири методи автентифікації. Методи 1–3 використовують SET LOCAL ROLE для перемикання ідентичності; метод 4 (прямі облікові дані) підключається безпосередньо як користувач, тож перемикання ролі не потрібне.

1. Інтерактивний вхід (JWT)

Користувачі автентифікуються за допомогою свого справжнього імені користувача та пароля PostgreSQL через метод JSON-RPC get_jwt. У разі успіху вони отримують короткостроковий JWT. Наступні запити передають цей токен у заголовку Authorization: Bearer <token>, і PgArachne перемикає активну роль на цього користувача на час виконання кожного запиту.

2. Сервісні облікові записи (API-токени)

Для автоматизованих систем або скриптів рекомендується використовувати довгострокові API-токени.

• Токени зберігаються в таблиці pgarachne.api_tokens.
• Кожен токен зіставлений із конкретною роллю бази даних.
• Надсилайте токен через заголовок Authorization: Bearer <token>.

Створення API-токенів вимагає pgarachne_admin. Використовуйте pgarachne.add_api_token(...) з роллю, яка є учасником pgarachne_admin.

3. Зовнішній постачальник ідентичності (власний JWT)

Якщо користувачі автентифікуються поза PgArachne (наприклад, через зовнішній сервіс автентифікації), ви можете видавати JWT там і надсилати їх безпосередньо до PgArachne.

• Формат заголовка: Authorization: Bearer <jwt>.
• Підписування: лише HMAC (HS256 / HS384 / HS512) із тим самим JWT_SECRET, який налаштовано в PgArachne.
• Обов’язкові claim-и: db_role (рядок, не порожній) та db_name (рядок, має відповідати сегменту шляху :database).
• Рекомендований claim: exp (Unix-часова метка) для терміну дії токена.

Приклад мінімального payload:

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

Примітка: асиметричні алгоритми JWT (наприклад, RS256 / ES256) не підтримуються.

4. Прямі облікові дані бази даних (Basic Auth)

Найпростіший варіант: надсилайте ім’я користувача та пароль PostgreSQL з кожним запитом, використовуючи стандартну HTTP Basic Authentication. PgArachne відкриває окремий пул з’єднань, автентифікований безпосередньо як цей користувач — SET LOCAL ROLE при цьому не виконується.

Authorization: Basic <base64(username:password)>

Приклад з 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}'

Ключові відмінності від методів на основі токенів:

• GRANT demo_user TO pgarachne не потрібен — PgArachne не перемикає ролі.
• Row-Level Security PostgreSQL та права доступу GRANT застосовуються як зазвичай, оскільки з’єднання виконується від імені фактичного користувача.
• Пули з’єднань підтримуються окремо для кожного користувача для ефективності, з максимальним часом життя 5 хвилин. Після зміни пароля старі з’єднання завершуються протягом цього вікна.
• Щоб ключі ідемпотентності працювали з прямими обліковими даними, надайте користувачеві право EXECUTE ON FUNCTION pgarachne.save_idempotency_key(text).

-- Потрібно лише для автентифікації через JWT / API-токен:
GRANT demo_user TO pgarachne;

Порівняння методів автентифікації

Дивіться також

• Конфігурація
• Коди помилок