Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

Керування доступом

Керування доступом сторін, що викликають, автентифікує сторону, що викликає, у сеансі StackQL та авторизує кожну інструкцію згідно з політикою. Воно не залежить від облікових даних провайдерів, які, як і раніше, передаються через --auth, змінні середовища або сеанси провайдерів. За замовчуванням його вимкнено, і розгортання, у яких його не ввімкнено, працюють так само, як раніше. Доступно в StackQL v1.0 і новіших версіях.

Див. також:
[ Глобальні прапорці ] [mcp] [whoami] [groups]


Увімкнення керування доступом​

Керування доступом вмикається запуском StackQL із глобальним прапорцем --access.config, який вказує на файл конфігурації JSON. Приклад запускає інтерактивну оболонку в захищеному режимі; exec і mcp вмикаються так само.

stackql --access.config '{"path": "/etc/stackql/access.json"}' shell

Прапорець --access.config приймає обгортку JSON з єдиним ключем path; простий шлях до файлу також приймається. Конфігурація завантажується один раз під час запуску, тому ротацію ключів або політики виконуйте через контрольований перезапуск.

Коли керування доступом увімкнено, виконуються лише exec, shell, mcp і version; інші команди, зокрема registry, відмовляються працювати, а не обходять захищений шлях. Команда srv і тип сервера MCP reverse_proxy також відмовляються працювати, оскільки залежність мережевого протоколу PostgreSQL поки що не надає підтверджень автентифікації для окремих з'єднань. Інструкції SQL AUTH і AUTH REVOKE у захищеному режимі відхиляються; натомість надавайте облікові дані провайдерів через конфігурацію хоста. Захищена команда exec, що завершилася помилкою, після виведення помилки повертає код завершення 1.

Режими автентифікації​

Файл конфігурації визначає один type: jwt (значення за замовчуванням, якщо його не вказано), bearer, mtls або local_os. Конфігурація - це строгий JSON: невідомі поля, а також поля, що належать до іншого режиму, відхиляються. Усі режими використовують ті самі rules і той самий каталог principal.

JWT​

Сторона, що викликає, надає підписаний токен, який перевіряється офлайн за ключами, закріпленими в конфігурації. Мінімальна конфігурація вказує видавця та аудиторію, які має містити токен, перелічує один відкритий ключ і дозволяє членам групи analysts виконувати інструкції читання (члени групи readers можуть робити це без правила, див. Правила політики):

{
"type": "jwt",
"issuer": "https://identity.example",
"audience": "stackql",
"keys": [
{"kid": "primary", "algorithm": "EdDSA", "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"}
],
"rules": [
{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}
]
}

Видавця, аудиторію та відкриті ключі закріплено в конфігурації; виявлення OIDC не використовується. Допустимі алгоритми: EdDSA, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 і ES512; ключі RSA мають бути завдовжки щонайменше 2048 біт. Кожен ключ прив'язано до налаштованого для нього алгоритму. Токени з невідомим ідентифікатором ключа, недійсним підписом, відсутнім або простроченим терміном дії, nbf або iat у майбутньому чи неправильним видавцем або аудиторією відхиляються. Claim груп і URL, що містяться в токені, не використовуються для довіри чи членства в каталозі.

Статичний токен bearer​

Сторона, що викликає, надає непрозорий токен, а конфігурація перелічує дайджест SHA-256 кожного прийнятного токена разом із суб'єктом, якого він ідентифікує. Цей режим підходить для невеликого фіксованого набору ідентичностей служб, коли запускати видавця токенів недоцільно:

{
"type": "bearer",
"issuer": "local-tokens",
"tokens": [{"subject": "alice", "sha256": "<64 hexadecimal characters: the SHA-256 of the token>"}],
"rules": [{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}]
}

У конфігурації вказується лише дайджест SHA-256 кожного токена, і дайджести мають бути унікальними. Зміна налаштованих дайджестів потребує перезапуску.

Взаємний TLS​

Сторону, що викликає, ідентифікує клієнтський сертифікат, який вона надає в транспорті MCP через HTTPS. Конфігурація містить CA, що має бути видавцем сертифіката, і визначає, яке альтернативне ім'я суб'єкта містить ідентичність:

{
"type": "mtls",
"issuer": "client-certificates",
"client_ca_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"certificate_identity": "uri_san",
"rules": [{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}]
}

Ланцюжок клієнтського сертифіката перевіряється за client_ca_pem, а суб'єкт ідентичності береться рівно з одного SAN налаштованого типу, uri_san або dns_san. Резервного варіанта з Common Name немає. Взаємний TLS доступний лише для транспорту MCP через HTTPS.

Ідентичність локальної ОС​

Облікові дані не передаються: суб'єктом є ідентичність операційної системи, від імені якої працює процес StackQL. Конфігурації потрібні лише мітка issuer і правила:

{
"type": "local_os",
"issuer": "this-host",
"rules": [{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}]
}

Суб'єктом ідентичності є ефективний UID Unix або SID Windows процесу StackQL, зокрема числові UID контейнерів без запису в passwd. Облікові дані не надаються, а STACKQL_CALLER_TOKEN ігнорується. Цей режим лише локальний: для викликів через HTTP його відхилено. Членство в групах операційної системи не надає доступу; доступ надає лише членство в каталозі.

Граничний термін сеансу​

За замовчуванням запити не мають граничного терміну, що випливає з автентифікації. Облікові дані перевіряються, а членство в каталозі оновлюється для кожної нової інструкції, тому прострочені облікові дані не можуть розпочати нову роботу, але закінчення терміну дії не перериває вже авторизовану інструкцію. Встановіть "enforce_session_deadline": true, щоб скасовувати виконання після max_session_seconds (за замовчуванням 300, максимум 86400), скорочене до закінчення терміну дії JWT або сертифіката. Токени при цьому не поновлюються.

Каталог principal​

Ідентичності зіставляються з principal, а principal - із групами в чотирьох таблицях налаштованого бекенду SQLite або PostgreSQL:

ТаблицяВміст
stackql_access_principalsІдентифікатор principal і об'єкт JSON з рядковими атрибутами. Атрибут tenant визначає простір імен стану IaC у попередній версії.
stackql_access_identitiesЗіставлення перевіреної пари (issuer, subject) з ідентифікатором principal.
stackql_access_groupsІдентифікатори груп.
stackql_access_membershipsПрив'язки principal до груп.

Перш ніж обслуговувати захищені запити, створіть таблиці, ідентичності та членства через довірене адміністративне з'єднання з базою даних:

INSERT INTO stackql_access_principals (id, attributes) VALUES ('alice', '{}');
INSERT INTO stackql_access_groups (id) VALUES ('readers');
INSERT INTO stackql_access_identities (issuer, subject, principal_id)
VALUES ('https://identity.example', 'alice', 'alice');
INSERT INTO stackql_access_memberships (principal_id, group_id) VALUES ('alice', 'readers');

Використовуйте фактичні видавця та суб'єкта режиму: для ідентичності локальної ОС це може бути ('this-host', '1000'), а для взаємного TLS - ('client-certificates', 'spiffe://example/alice'). Явно виберіть бекенд:

stackql --access.config '{"path":"/etc/stackql/access.json"}' \
--sqlBackend '{"dbEngine":"postgres_tcp","dsn":"postgres://runtime@localhost/stackql?sslmode=require","sqlDialect":"postgres"}' \
exec 'SELECT whoami(), groups();'

Каталог створює незмінний знімок для кожної інструкції. Відкликання - це DELETE FROM stackql_access_memberships в адміністративному з'єднанні; наступна інструкція бачить новий знімок. Невідомі ідентичності, відсутня схема, неправильно сформовані дані та збої каталогу - усе це призводить до відмови в доступі. Звичайний захищений SQL не може звертатися до таблиць каталогу. Виконуйте операції запису членства лише через адміністративне з'єднання, захистіть файл бази даних і використовуйте окремі привілеї бази даних для адміністрування та для середовища виконання, якщо бекенд їх підтримує.

Правила політики​

Кожне правило надає одну дію action над одним ресурсом resource суб'єкту subject у формі group:<group id>. Використовуйте скомпільовані ідентифікатори методів і операцій із довірених документів провайдерів; символ узагальнення для операцій надає доступ не лише до читання, а й до методів змінення даних.

Група readers неявно має можливість хоста щодо безпечного читання через SQL. Операції читання для principal поза цією групою потребують host/sql/read, а інші інструкції потребують execute для host/sql/<statement kind>. Операції провайдерів і використання облікових даних завжди потребують явних правил, а надання доступу до колекції не надає доступу до її базових методів. Додаткові перевірки хоста:

РесурсДіяОбласть
host/sql/readexecuteІнструкції читання поза неявною групою читачів
host/sql/execexecuteНативна інструкція EXEC, зокрема вкладена інструкція EXEC
host/iac/run, host/iac/destroyexecuteВідношення IaC у попередній версії, попри їхній синтаксис SELECT
host/function/<name>executeФункції поза невеликим списком дозволених відомих чистих функцій
host/backendreadНепрозорі збережені та зовнішні відношення бекенду
host/credentialsreloadІнструмент MCP reload_credentials
session/variablesreadРозіменування змінних сеансу і секретів
session/configwriteSET і UNSET

Розкриття збережених запитів перевіряється перед виконанням, а повторне використання кешу планів і рядків на захищених шляхах вимкнено.

Точки входу​

Автентифікаціяexec, shell, MCP через stdioMCP через HTTPS
JWTЗмінна середовища STACKQL_CALLER_TOKENЗаголовок запиту Authorization: Bearer
Статичний bearerЗмінна середовища STACKQL_CALLER_TOKENЗаголовок запиту Authorization: Bearer
Локальна ОСЕфективний UID або SID процесу; без облікових данихВідхилено
Взаємний TLSВідхилено: немає перевіреного з'єднання TLSПеревірений клієнтський ланцюжок і один налаштований SAN

Передавайте локальні облікові дані у вигляді токенів через середовище процесу і в жодному разі не як літерал SQL або аргумент командного рядка. Через HTTPS засіб перевірки сторони, що викликає, замінює спільний контроль bearer через auth_token_env_var, описаний у розділі Автентифікація клієнтів HTTP; конфігурація сертифіката й ключа TLS сервера обов'язкова, а запит без облікових даних ніколи не переходить на токен із середовища сервера.

Перевірка сторони, що викликає​

В автентифікованому сеансі функція whoami() повертає ідентифікатор principal, а функція groups() - групи каталогу у вигляді масиву JSON:

SELECT whoami() AS principal, groups() AS memberships;
|-----------|-------------|
| principal | memberships |
|-----------|-------------|
| alice | ["readers"] |
|-----------|-------------|

Обидві функції потребують сеансу, запущеного з прапорцем --access.config.

Покрокові керівництва​

Репозиторій StackQL містить чотири виконувані покрокові керівництва, по одному для кожного режиму автентифікації; їх запускає скрипт Python, який створює демонстраційний каталог і перевіряє запит. Для них не потрібен обліковий запис у хмарі, і їх запускає набір тестів проєкту.