Создание и использование API-токенов
В этом сценарии покажем, как выпустить API-токен для программного доступа к Tengri и использовать его для аутентификации, а также как просматривать, обновлять и отзывать токены. В конце рассмотрим действия администратора: ограничение срока действия токенов и выпуск токена для другого пользователя.
API-токены удобны там, где не подходит интерактивный вход по паролю: в скриптах, задачах CI/CD, BI-инструментах и других интеграциях. Токен привязан к пользователю и наследует все его роли и привилегии.
| Полное описание команд и параметров для API-токенов приведено на странице Операции с API-токенами. |
Выпуск токена
Выпустим токен для текущего пользователя. Дадим ему понятное имя, ограничим срок действия 30 днями и добавим комментарий с назначением.
CREATE API TOKEN ci_pipeline
MAX DURATION '30d'
COMMENT 'Токен для сборочного конвейера';
+-------------+------------------------------------------------------+---------------------------+
| name | token | expires_at |
+-------------+------------------------------------------------------+---------------------------+
| ci_pipeline | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoi... | 2026-07-20T09:00:00+00:00 |
+-------------+------------------------------------------------------+---------------------------+
Значение из колонки token показывается единственный раз и не может быть восстановлено. Сразу сохраните его в надежном месте (например, в секретах CI/CD). Если токен утерян или скомпрометирован, отзовите его и выпустите новый.
|
Имя и срок действия можно не указывать. Тогда система сгенерирует имя автоматически, а срок действия по умолчанию составит 365 дней:
CREATE API TOKEN;
Использование токена для аутентификации
Полученный токен предъявляется при каждом обращении к Tengri. Запрос будет успешен, только если он выполняется от имени пользователя, выпустившего токен.
Доступ по HTTP
При обращении к HTTP-шлюзу токен передается в заголовке Authorization:
curl -H "Authorization: Bearer <token>" \
https://<tengri-host>/api/...
Альтернативно токен можно передать в cookie auth_token.
Доступ через библиотеку tngri
В Python-библиотеке tngri токен передается в поле ws_token конфигурации клиента. Клиент аутентифицирует WebSocket соединение под владельцем токена:
import tngri
config = tngri.config.Config(
ws_addr='ws://<tengri-host>:3001', # адрес WebSocket-шлюза Tengri
ws_token='<token>', # значение токена, полученное из результата CREATE API TOKEN
)
client = tngri.Client(config)
# Запрос выполняется от имени владельца токена со всеми его правами
df = client.sql('SELECT 1 AS answer')
print(df)
Адрес шлюза и токен можно вынести в переменные окружения TNGRI_SITE_WS_ADDR и TNGRI_ACCESS_TOKEN — тогда клиент создается из окружения без явной передачи токена в коде:
import tngri
client = tngri.Client.from_env()
df = client.sql('SELECT 1 AS answer')
print(df)
$ TNGRI_SITE_WS_ADDR=ws://tengri.example.com:3001 \
TNGRI_ACCESS_TOKEN=<token>\
python script.py
| Храните значение токена как секрет: передавайте его через переменные окружения или хранилище секретов CI/CD, а не записывайте в исходный код. |
Просмотр своих токенов
Список выпущенных токенов можно получить командой:
SHOW API TOKENS;
Подробное описание команды см. здесь.
Изменение комментария
Комментарий к токену можно обновить, не меняя само значение токена и его срок действия:
ALTER API TOKEN ci_pipeline SET COMMENT 'Перенесен на новый раннер';
Подробное описание команды см. здесь.
Отзыв токена
Чтобы немедленно прекратить действие токена, отзовите его:
DROP API TOKEN ci_pipeline;
Подробное описание команды см. здесь.
Отзыв — правильная реакция на компрометацию или плановую ротацию токена. При подозрении на компрометацию учетной записи можно отозвать сразу все токены пользователя:
DROP ALL API TOKENS FOR USER <user_name>;
Подробное описание команды см. здесь.
Администрирование токенов
Следующие действия доступны только администратору (пользователю с привилегией ADMIN ON CATALOG или встроенному пользователю admin).
Ограничение срока действия токенов
По умолчанию пользователь может выпустить токен сроком до 365 дней. Чтобы ограничить максимальный срок действия токенов, администратор задает политику на уровне пользователя или роли.
-
Ограничим срок действия токенов пользователя
analystодними сутками:ALTER USER analyst SET API TOKEN MAX DURATION '24h'; -
Или ограничим срок действия для всех обладателей роли
service_accounts30 днями:ALTER ROLE service_accounts SET API TOKEN MAX DURATION '30d';
После установки политики попытка выпустить токен с бОльшим сроком действия будет отклонена с ошибкой. Если у пользователя есть несколько применимых ограничений (личное и по ролям), действует наименее ограничивающее (наибольший срок).
Подробное описание команды см. здесь.
Выпуск и управление токенами другого пользователя
Администратор может управлять токенами любого пользователя, добавляя к командам параметр FOR USER.
-
Выпустим токен для пользователя
analystот его имени:CREATE API TOKEN report_bot FOR USER analyst MAX DURATION '90d' COMMENT 'Сервисный токен для выгрузки отчетов'; -
Посмотрим токены пользователя
analyst:SHOW API TOKENS FOR USER analyst; -
При необходимости отзовем токен этого пользователя:
DROP API TOKEN report_bot FOR USER analyst;
Без параметра FOR USER все команды действуют над токенами текущего пользователя. Обычный пользователь (не администратор) параметр FOR USER использовать не может.
|
Управление токенами в веб-интерфейсе
Управлять токенами можно не только через команды SQL, но и в веб-интерфейсе Tengri: во вкладке Настройки > API-токены. На этой странице доступно полноценное управление токенами текущего пользователя:
-
создание токена с указанием имени, срока действия и комментария;
-
однократный показ значения нового токена после создания с кнопкой копирования;
-
редактирование комментария;
-
отзыв токена;
-
просмотр действующих токенов (с возможностью скрытия истекших и отозванных).