Агенты > Pastukhov Agent > Документация > Ключи доступа

Ключи доступа

Ключ доступа открывает вход в агент из другой программы — без пароля и без формы входа. У каждого устройства или скрипта может быть свой ключ с понятным именем: видно, кто чем пользуется, а отзыв одного ключа не мешает остальным. Здесь — как выдать такой ключ, где он хранится и что именно он открывает.

Зачем это нужно

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

Именованные ключи решают эту задачу: заводите отдельный ключ на каждое устройство, программу или исполнителя и даёте ему понятное имя. Из списка сразу видно, кто чем пользуется. Удаление или перегенерация одного ключа останавливает только его — остальные продолжают работать.

Ключи лежат в файле внутри проекта и вместе с проектом попадают в систему контроля версий. Хранятся там только соль и хеши, сами ключи в файл не записываются, поэтому его безопасно сохранять и передавать.

Где управлять ключами

Ключи создаются и правятся в разделе Настройки → группа «Конфигурация» → карточка «Ключи доступа».

Изменения сохраняются сразу: у каждого действия свой отдельный результат, кнопки «Сохранить» нет. Поэтому диалог можно закрыть в любой момент — ничего не потеряется.

Список ключей

Каждый ключ занимает в списке отдельную строку: слева имя и первые 12 символов хеша, справа три действия.

  • Переименовать — сменить имя, не трогая сам ключ;
  • Перегенерировать — выпустить новый ключ под тем же именем; прежний ключ сразу перестаёт работать;
  • Удалить — отозвать ключ.

Удаление и перегенерация сначала спрашивают подтверждение и прямо предупреждают: текущий ключ перестаёт работать немедленно.

Как создать ключ

  1. Нажмите «Сгенерировать ключ».
  2. В окне «Новый ключ доступа» введите имя — от 1 до 64 символов: буквы, цифры, подчёркивание или дефис. Имена не должны повторяться, регистр не важен.
  3. Подтвердите — ключ появится в списке.

Сразу после создания ключ показывается один раз в отдельной панели: полный ключ в поле с кнопкой копирования и предупреждение «Скопируйте ключ сейчас — он больше не будет показан». Скопируйте ключ и передайте тому, для кого он предназначен. Рядом есть кнопка «Копировать хеш» — она пригодится, если нужно сверить запись в файле.

Ключ имеет вид agent_ и ещё 32 случайных символа из латинских букв и цифр. Приставка agent_ помогает узнать ключ, когда он лежит рядом с другими ключами и токенами.

Посмотреть ключ позже нельзя: после закрытия панели в системе остаётся только его хеш. Если ключ потерян, выпустите новый под тем же именем через «Перегенерировать».

Как пользоваться ключом

Ключ передаётся в заголовке X-API-Key — точно так же, как ключ из переменной окружения:

X-API-Key: agent_ваш-ключ

Для живых подключений (WebSocket/SignalR) заголовки задать нельзя, поэтому тот же ключ передаётся параметром адреса:

/svelteChatHub?api_key=agent_ваш-ключ

Подробнее о командах, адресах и примерах запросов — на странице API.

Что даёт ключ

Действительный ключ даёт полный доступ: он открывает вызывающему все адреса /api/* и подписку на живые события с ролью менеджера — тот же доступ, что и вход менеджером, и без срока действия.

Предъявленный неверный ключ отклоняется с ошибкой 401 Unauthorized на любом адресе API — даже если рядом передан правильный токен входа.

Если ключ не передавать, ничего не меняется: работает обычный вход в интерфейс. Сам интерфейс агента ключ не отправляет — именованные ключи нужны только внешним программам.

Удаление и перегенерация действуют сразу — перезапускать агент не нужно.

Файл keys.yml

Все именованные ключи хранятся в файле keys.yml в папке проекта — .pastukhov/keys.yml:

salt: 9f1c...        # соль — 64 шестнадцатеричных символа, создаётся один раз
keys:
  - name: laptop
    hash: a3b5c...   # SHA256(соль + ключ), 64 шестнадцатеричных символа
  - name: ci-runner
    hash: 77d0e...

Каждый ключ записан только как хеш SHA256(соль + ключ). Соль — общая для всех ключей случайная строка, она создаётся один раз при появлении файла. Сам ключ нигде не сохраняется, восстановить его из файла нельзя.

Файл создаётся при первом ключе, отдельно подготавливать его не нужно. Его безопасно коммитить в репозиторий: внутри только соль и хеши.

Вручную файл правится в разделе Настройки → «Настройки проекта» → вкладка keys.yml — например, чтобы добавить ключ, посчитав его хеш по той же формуле.

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

Включение Remote API

Адреса /api/remote работают, когда задана переменная AGENT_API_KEY или в файле есть хотя бы один именованный ключ. Одного именованного ключа для включения достаточно.

Если не задано ни то, ни другое, удалённые запросы получают ответ 503 Service Unavailable с пояснением, что нужен ключ доступа.

Подробнее — на страницах API и Удалённое управление.

  • API — команды, адреса и авторизация по ключу;
  • Вход и авторизация — все способы доступа к агенту;
  • Папка .pastukhov — где хранятся настройки проекта, включая keys.yml;
  • Настройки — карточный центр настроек и карточка «Ключи доступа».

← Назад: Вход и авторизация

Далее: Начало работы →