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

> Явно ввімкнене керування доступом у StackQL: автентифікація через JWT, токени bearer, взаємний TLS або ідентичність локальної ОС, principal і групи в каталозі, авторизація інструкцій за правилами політики.

Source: https://stackql.io/uk/command-line-usage/access-management

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

Див. також:  
[[ Глобальні прапорці ]](/command-line-usage/global-flags) [[` mcp `]](/command-line-usage/mcp) [[` whoami `]](/language-spec/functions/session/whoami) [[` groups `]](/language-spec/functions/session/groups)

* * * 

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

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

```bash
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](#principal-directory).

### JWT

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

```json
{
  "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 кожного прийнятного токена разом із суб'єктом, якого він ідентифікує. Цей режим підходить для невеликого фіксованого набору ідентичностей служб, коли запускати видавця токенів недоцільно:

```json
{
  "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, що має бути видавцем сертифіката, і визначає, яке альтернативне ім'я суб'єкта містить ідентичність:

```json
{
  "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` і правила:

```json
{
  "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 до груп. |

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

```sql
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')`. Явно виберіть бекенд:

```bash
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/read` | `execute` | Інструкції читання поза неявною групою читачів |
| `host/sql/exec` | `execute` | Нативна інструкція `EXEC`, зокрема вкладена інструкція `EXEC` |
| `host/iac/run`, `host/iac/destroy` | `execute` | Відношення IaC у попередній версії, попри їхній синтаксис `SELECT` |
| `host/function/<name>` | `execute` | Функції поза невеликим списком дозволених відомих чистих функцій |
| `host/backend` | `read` | Непрозорі збережені та зовнішні відношення бекенду |
| `host/credentials` | `reload` | Інструмент MCP `reload_credentials` |
| `session/variables` | `read` | Розіменування [змінних сеансу](/getting-started/session-variables) і секретів |
| `session/config` | `write` | `SET` і `UNSET` |

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

## Точки входу

| Автентифікація | `exec`, `shell`, MCP через stdio | MCP через 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](/command-line-usage/mcp#http-client-authentication); конфігурація сертифіката й ключа TLS сервера обов'язкова, а запит без облікових даних ніколи не переходить на токен із середовища сервера.

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

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

```sql
SELECT whoami() AS principal, groups() AS memberships;
```

```
|-----------|-------------|
| principal | memberships |
|-----------|-------------|
| alice     | ["readers"] |
|-----------|-------------|
```

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

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

Репозиторій StackQL містить [чотири виконувані покрокові керівництва](https://github.com/stackql/stackql/blob/main/docs/examples/access-management/README.md), по одному для кожного режиму автентифікації; їх запускає скрипт Python, який створює демонстраційний каталог і перевіряє запит. Для них не потрібен обліковий запис у хмарі, і їх запускає набір тестів проєкту.
