Перейти к содержанию

Авторизованный ключ

ИИ Студия использует авторизованный ключ служебной учётной записи как серверные учётные данные для Яндекс Облако.

Это не пароль пользователя и не статический IAM-токен.

Закрытая часть RSA-ключа позволяет Студии подписать JWT, обменять его на IAM-токен и затем обращаться к разрешённым API от имени служебная учётная запись.

Что вы сделаете

На этой странице вы:

  1. создадите ключ в Яндекс Облаке;
  2. сохраните JSON;
  3. загрузите его в ИИ Студию;
  4. проверите, что ключ принят;
  5. разберётесь, где он хранится;
  6. научитесь безопасно ротировать его.

1. Что находится в JSON

Типичный файл содержит поля следующего вида:

{
  "id": "<key-id>",
  "service_account_id": "<service-account-id>",
  "created_at": "<timestamp>",
  "key_algorithm": "RSA_2048",
  "public_key": "-----BEGIN PUBLIC KEY----- ...",
  "private_key": "-----BEGIN PRIVATE KEY----- ..."
}

Значение private_key является секретом.

Danger

Никогда не вставляйте настоящий JSON ключа в чат, тикет, Git, Wiki, README, скриншот или письмо. Если закрытый ключ попал в чужие руки, считайте ключ скомпрометированным и удалите его в Яндекс Облако.

2. Почему ключ долгоживущий, а IAM-токен — нет

У авторизованного ключа нет обычного короткого срока жизни.

Он используется для периодического получения IAM-токенов.

Схема:

authorized key
    ↓
подписанный JWT
    ↓
Yandex IAM
    ↓
краткоживущий IAM token
    ↓
вызов API

Студия не должна заставлять администратора вручную копировать новые IAM-токены каждый несколько часов.

3. Создать ключ через консоль

  1. Откройте нужный каталог Яндекс Облака.
  2. Перейдите в Identity and Access Management.
  3. Откройте Сервисные аккаунты.
  4. Выберите служебная учётная запись ИИ Студии.
  5. Нажмите Создать новый ключ.
  6. Выберите Создать авторизованный ключ.
  7. Выберите RSA-алгоритм.
  8. Укажите описание, например:
NiceSoft AI Studio production
  1. Нажмите Создать.
  2. Сохраните закрытую часть/JSON сразу.

Закрытую часть позднее повторно получить нельзя.

4. Создать ключ через CLI

Пример:

yc iam key create \
  --service-account-name nicesoft-ai-studio \
  --output nicesoft-ai-studio-key.json

После выполнения убедитесь, что файл существует:

ls -l nicesoft-ai-studio-key.json

Не выводите его содержимое в терминал во время демонстрации или записи экрана.

5. Как загрузить ключ в Студию

  1. Войдите как ADMIN.
  2. Откройте Интеграция с YC.
  3. Перейдите в Подключение YC.
  4. Найдите блок Авторизованный ключ.
  5. Выберите JSON.
  6. Проверьте, что файл относится к нужному служебная учётная запись.
  7. Подтвердите загрузку.
  8. Дождитесь результата проверки.

Студия проверяет ключевой JSON на сервере.

6. Что проверяет NiceSoft Шлюз

Точный набор внутренних проверок может развиваться, но текущая реализация как минимум проверяет необходимые поля и ключевой материал, затем использует RSA закрытый ключ для JWT PS256.

В интерфейс возвращается только безопасная информация о ключе, например:

  • факт наличия;
  • идентификатор ключа;
  • ID служебной учётной записи;
  • алгоритм;
  • дата создания;
  • дата импорта;
  • связанный home каталог/облако;
  • имя служебной учётной записи, если оно определено.

Закрытый ключ обратно в браузер не выдаётся.

7. Где хранится секрет

В текущей архитектуре:

  • ключ хранится на стороне сервера;
  • каталог секрета создаётся с ограниченными правами;
  • файл ключа хранится с правами только владельца;
  • IAM token кэшируется в памяти шлюз;
  • браузер не получает закрытый ключ;
  • браузер не получает IAM token;
  • Billing сервис получает ключ через внутреннее подключение только для чтения;
  • секрет не должен попадать в запрос модели.

Это принципиальное отличие от подхода «положить ключ в браузер и вызывать API напрямую».

8. Ключ не определяет рабочий каталог

После загрузки ключа Студия уже знает, кто выполняет запросы.

Но ей ещё нужно знать, где обычным пользователям разрешено работать.

Поэтому отдельно выполняется привязка рабочего каталога.

ключ = субъект
Folder pairing = рабочая область

Не путайте эти понятия.

9. Ключ не заменяет роли

Наличие валидного ключа не даёт служебная учётная запись новых прав.

Если учётная запись не имеет роли compute.viewer, viewer, billing.accounts.viewer, ai.languageModels.user или другой необходимой роли, API вернёт отказ.

То есть:

валидный ключ + нет роли = 403

а не:

валидный ключ = полный доступ

10. Как ротировать ключ

Ротация нужна:

  • по внутренней политике;
  • при смене администратора;
  • при подозрении на компрометацию;
  • если файл случайно попал в лог/чат/repository;
  • при плановой замене учётные данные.

Безопасная последовательность:

  1. создайте новый авторизованный ключ для той же служебной учётной записи;
  2. загрузите новый JSON в Студию;
  3. проверьте yc-doctor;
  4. проверьте инфраструктурный запрос;
  5. проверьте Billing;
  6. проверьте Yandex AI, если используется;
  7. только после успешного теста удалите старый ключ в Яндекс Облако.

Так вы избегаете незапланированного простоя.

11. Как удалить ключ из Студии

Удаление учётные данные в Студии и удаление ключа в Яндекс Облаке — разные действия.

Для полного отзыва:

  1. удалите/отключите ключ в Яндекс Облаке;
  2. удалите сохранённый ключ в ИИ Студии;
  3. проверьте, что yc-doctor больше не получает IAM учётные данные;
  4. убедитесь, что облачные сервисы не выполняют запросы.

Если удалить только локальный файл, ключ продолжит существовать в Yandex IAM.

Если удалить только объект ключа в Яндекс Облако, локальный JSON станет бесполезным, но всё равно останется секретным материалом и должен быть удалён.

12. Что делать при утечке

Если закрытый ключ попал:

  • в Git;
  • в чат;
  • в публичный issue;
  • в письмо неизвестному получателю;
  • в скриншот;
  • в support bundle без редактирования;

не пытайтесь «спрятать» старую публикацию и продолжить пользоваться ключом.

Выполните:

  1. немедленно удалите ключ в Яндекс Облако;
  2. создайте новый;
  3. загрузите новый в Студию;
  4. проверьте аудит и last_used_at, если доступно;
  5. выясните, какие права были у служебная учётная запись в момент утечки;
  6. при необходимости временно сократите роли;
  7. проверьте журналы доступа.

13. Ошибки при загрузке

«Некорректный JSON»

Проверьте, что вы загрузили именно файл авторизованного ключа, а не:

  • API-ключ;
  • IAM token;
  • SSH закрытый ключ;
  • OAuth token;
  • произвольный JSON из Terraform state.

«Не найден private_key»

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

Создайте новый ключ — закрытую часть старого получить повторно нельзя.

«Unsupported key algorithm»

Используйте поддерживаемый RSA авторизованный ключ, созданный стандартным механизмом Yandex IAM.

Ключ принят, но 403

Проблема обычно не в ключе, а в ролях или область доступа.

Перейдите к Права служебной учётной записи.

14. Что нельзя делать с ключом

Не следует:

  • хранить его в /tmp без контроля прав;
  • добавлять в .env, если этот .env попадает в backup для разработчиков;
  • коммитить в Git;
  • копировать на рабочие станции пользователей;
  • передавать USER-роли;
  • вставлять в запрос;
  • использовать один ключ для десятка несвязанных систем;
  • пересылать в мессенджер;
  • делать screenshot содержимого JSON;
  • оставлять старые ключи активными после ротации.

15. Контрольный тест

После загрузки выполните:

./nicesoft.sh yc-doctor

Проверьте минимум:

Credential source: authorized_key
IAM auth available: YES
Authorized key file: present / readable

Если эти пункты успешны, учётные данные-уровень работает.

Если каталог ещё не привязан, предупреждение о привязке в этот момент допустимо.

Что дальше