Операции с API-токенами

API-токен — это долгоживущий отзываемый токен доступа, который пользователь может самостоятельно выпустить с помощью команд SQL. Токен предъявляется для аутентификации при обращении к Tengri по HTTP и WebSocket (например, из скриптов, CI/CD, BI-инструментов и других программных клиентов).

В отличие от пароля, API-токен:

выпускается и отзывается отдельными командами и не требует ввода пароля при каждом обращении;
привязан к конкретному пользователю и наследует его роли и привилегии;
имеет ограниченный срок действия и может быть отозван в любой момент;
хранится в системе только в виде хеша — сам токен невозможно восстановить после выпуска.

Значение токена показывается ровно один раз — в выводе команды CREATE API TOKEN. Сохраните его сразу: восстановить токен позже невозможно. При утере достаточно отозвать старый токен и выпустить новый.

Команды управления токенами

CREATE API TOKEN — Выпуск токена
ALTER API TOKEN — Изменение комментария к токену
DROP API TOKEN — Отзыв токена
DROP ALL API TOKENS — Отзыв всех токенов пользователя
SHOW API TOKENS — Вывод списка всех токенов

По умолчанию пользователь управляет только своими токенами. Управление токенами другого пользователя (через параметр FOR USER) доступно только администратору. Подробнее см. Модель авторизации.

Выпуск токена

CREATE API TOKEN [<name>]
    [FOR USER <user_name>]
    [MAX DURATION '<duration>']
    [COMMENT '<text>'];

Выпускает новый API-токен и возвращает его значение. Все параметры опциональны.

В результате выполнения команды возвращается одна строка с тремя колонками:

+----------+----------------------------------------------+---------------------------+
| name     | token                                        | expires_at                |
+----------+----------------------------------------------+---------------------------+
| ...      | ...                                          | ...                       |
+----------+----------------------------------------------+---------------------------+

name — имя выпущенного токена;
token — значение токена (показывается единственный раз);
expires_at — момент истечения срока действия в UTC.

Значение в колонке token — это секретная информация, эквивалентная паролю. Если значение скомпрометировано, немедленно отзовите токен командой DROP API TOKEN.

Параметр `<name>`

Опциональное имя токена. Имя должно быть уникальным среди токенов одного пользователя. Если имя не указано, система генерирует его автоматически в формате <user>_<uuid>.

Параметр `FOR USER`

Опциональный параметр FOR USER <user_name> выпускает токен от имени другого пользователя. Доступен только администратору (см. Модель авторизации). Если параметр опущен, токен выпускается для текущего пользователя.

Параметр `MAX DURATION`

Опциональный параметр MAX DURATION '<duration>' задает запрашиваемый срок действия токена. Если параметр не указан, срок действия по умолчанию равен 365 дням.

Запрашиваемый срок действия не может превышать максимальный срок, установленный для пользователя или его ролей политикой SET API TOKEN MAX DURATION:

если запрошенный срок превышает установленный порог, команда завершится ошибкой;
если параметр MAX DURATION опущен, то токен будет выпущен с минимальным сроком действия среди всех ограничений пользователя.

Значение <duration> — строка, состоящая из сегментов вида число+единица. Поддерживаемые единицы:

s — секунды
m — минуты
h — часы
d — дни

Сегменты можно комбинировать, например: '30d', '24h', '1h30m', '2h45m30s'.

Параметр `COMMENT`

Опциональный параметр COMMENT '<text>' добавляет к токену произвольное текстовое описание (например, назначение токена или имя сервиса, который его использует). Комментарий можно изменить позже командой ALTER API TOKEN.

Посмотреть примеры

Выпуск токена для себя с именем и сроком действия по умолчанию и с пустым комментарием:
```
CREATE API TOKEN;
```
Именованный токен со сроком действия 30 дней и комментарием:
```
CREATE API TOKEN ci_pipeline
    MAX DURATION '30d'
    COMMENT 'Основная сборка';
```
Выпуск токена для другого пользователя (только для администратора):
```
CREATE API TOKEN report_bot
    FOR USER analyst
    MAX DURATION '90d';
```

Изменение комментария к токену

ALTER API TOKEN '<name>' [FOR USER <user_name>] SET COMMENT '<text>';

Изменяет комментарий к существующему токену. Значение токена и его срок действия при этом не меняются.

Параметр FOR USER <user_name> изменяет токен другого пользователя и доступен только администратору (см. Модель авторизации).

Посмотреть пример

ALTER API TOKEN ci_pipeline SET COMMENT 'Перенесен на новый раннер';

Отзыв токена

DROP API TOKEN '<name>' [FOR USER <user_name>];

Отзывает указанный токен.

После отзыва токен немедленно перестает действовать на всех путях аутентификации — повторная активация невозможна.

Параметр FOR USER <user_name> отзывает токен другого пользователя и доступен только администратору (см. Модель авторизации).

В случае компрометации, утери или необходимости заменить токен рекомендуется сразу отзывать токен через эту команду.

Посмотреть пример

DROP API TOKEN ci_pipeline;

Отзыв всех токенов пользователя

DROP ALL API TOKENS [FOR USER <user_name>];

Отзывает все действующие токены пользователя одной командой.

Полезно при подозрении на компрометацию учетной записи.

Параметр FOR USER <user_name> отзывает токены другого пользователя и доступен только администратору (см. Модель авторизации).

Команда отзывает сразу все действующие токены пользователя. Все клиенты, использующие эти токены (скрипты, CI/CD, интеграции), потеряют доступ к системе и потребуют выпуска новых токенов.

Вывод списка всех токенов

SHOW API TOKENS [FOR USER <user_name>];

Выводит список всех токенов пользователя.

Значения токенов при этом не выводятся — они недоступны для просмотра после выпуска. Список включает как действующие, так и отозванные и истекшие токены.

Параметр FOR USER <user_name> выводит токены другого пользователя и доступен только администратору (см. Модель авторизации). Если администратор не указывает этот параметр, то выводятся только токены, выпущенные им самим.

Формат вывода:

+------+--------------+------------+------------+------------+---------+
| name | last_used_at | created_at | expires_at | revoked_at | comment |
+------+--------------+------------+------------+------------+---------+
| ...  | ...          | ...        | ...        | ...        | ...     |
+------+--------------+------------+------------+------------+---------+

name — имя токена;
last_used_at — момент последнего использования токена (пусто, если токен ни разу не использовался);
created_at — момент выпуска;
expires_at — момент истечения срока действия;
revoked_at — момент отзыва (пусто для действующих токенов);
comment — комментарий к токену.

Все временные метки возвращаются в UTC.

Метка last_used_at обновляется не чаще одного раза в 5 минут, поэтому самые свежие обращения могут отображаться с небольшой задержкой.

Команды управления политикой действия токенов

ALTER <USER | ROLE> SET API TOKEN MAX DURATION — Ограничение максимального срока действия токенов

Ограничение максимального срока действия токенов

ALTER USER <user_name> SET API TOKEN MAX DURATION '<duration>';

ALTER ROLE <role_name> SET API TOKEN MAX DURATION '<duration>';

Устанавливает максимальный срок действия для токенов, выпускаемых пользователем или ролью.

Формат <duration> совпадает с форматом параметра MAX DURATION команды CREATE API TOKEN.
При выпуске токена применяется наименее ограничивающий (наибольший) порог среди тех, что установлены для самого пользователя и всех его действующих ролей.
Запрос токена со сроком действия, превышающим порог, отклоняется. Срок по умолчанию при наличии порога тоже ограничивается этим порогом'.

Эту политику может задавать только пользователь с правом администрирования (см. Модель авторизации).

Посмотреть примеры

Ограничить срок действия токенов пользователя analyst одним днем:
```
ALTER USER analyst SET API TOKEN MAX DURATION '24h';
```
Ограничить срок действия токенов роли service_accounts 30 днями:
```
ALTER ROLE service_accounts SET API TOKEN MAX DURATION '30d';
```

Модель авторизации

Управление токенами разделено на два уровня доступа.

Действие Кто может выполнять

Действие	Кто может выполнять
Управление своими токенами (без `FOR USER`)	Любой пользователь — без дополнительных привилегий.
Управление токенами другого пользователя (с `FOR USER`)	Только администратор.
Установка политики `SET API TOKEN MAX DURATION`	Только администратор.

Управление своими токенами (без FOR USER)

Любой пользователь — без дополнительных привилегий.

Управление токенами другого пользователя (с FOR USER)

Только администратор.

Установка политики SET API TOKEN MAX DURATION

Только администратор.

Администратором считается пользователь с привилегией ADMIN ON CATALOG, а также встроенный пользователь admin.

Самостоятельное управление своими токенами не требует отдельных привилегий: каждый пользователь может выпускать, просматривать и отзывать собственные токены.

Использование токена для аутентификации

Выпущенный токен предъявляется при каждом обращении к HTTP и WebSocket шлюзам Tengri одним из двух способов:

в заголовке HTTP-запроса Authorization: Bearer <token>;
в cookie auth_token=<token>.

Токен аутентифицирует клиента как его владельца, поэтому действуют все роли и привилегии этого пользователя.

Посмотреть пример

Обращение к REST-шлюзу с токеном в заголовке Authorization:
```
curl -H "Authorization: Bearer <token>" \
     https://<tengri-host>/api/...
```

Свойства безопасности

Хранение только в виде хеша. В базе данных хранится только хеш токена — само значение не сохраняется. Утечка базы данных не раскрывает значений, пригодных для аутентификации.
Немедленный отзыв. При каждой аутентификации проверяется не только подпись токена, но и его актуальность в хранилище, поэтому команда DROP API TOKEN действует немедленно, а не «до истечения срока».
Выделенный ключ подписи. Токены подписываются отдельным ключом, производным от мастер-ключа развертывания; ротация мастер-ключа автоматически ротирует и ключ подписи токенов.
Ограничение срока действия. Политика SET API TOKEN MAX DURATION ограничивает максимальное время жизни токенов на уровне пользователя или роли.

Операции с API-токенами

Команды управления токенами

Выпуск токена

Параметр <name>

Параметр FOR USER

Параметр MAX DURATION

Параметр COMMENT

Изменение комментария к токену

Отзыв токена

Отзыв всех токенов пользователя

Вывод списка всех токенов

Команды управления политикой действия токенов

Ограничение максимального срока действия токенов

Модель авторизации

Использование токена для аутентификации

Свойства безопасности

Полезные ссылки

Параметр `<name>`

Параметр `FOR USER`

Параметр `MAX DURATION`

Параметр `COMMENT`