Ротация токенов коннектора

Токен коннектора (ss_connector_*) — единственный credential, который нужен CMS-модулю. Он авторизует запись в AACsearch и переживает рестарты модуля. Эта страница — полный жизненный цикл и процедура ротации, которую оператору стоит запускать по расписанию.

Краткая модель токена

• Префикс: ss_connector_
• Область действия: connector_write (только запись через Connector API — без чтения, без админки)
• Хранится: SHA-256 хеш (prefix:hash) в SearchApiKey.hash
• Plaintext возвращается один раз при создании, никогда повторно
• Привязан к: одной организации (арендатор) и одному поисковому индексу
• Переиспользуется между: любым числом инстансов CMS, смотрящих на тот же индекс

Plaintext показывается в панели один раз. API для последующего получения plaintext не существует. Если токен потерян — единственный путь — ротация.

Создание токена

1. Панель → Connectors → New Connector Token.
2. Выберите поисковый индекс, в который будет писать токен.
3. (Опционально) Дайте лейбл, описывающий назначение токена — prestashop-staging, bitrix-prod, shopify-eu.
4. Нажмите Create. Сразу скопируйте plaintext и положите в secrets manager.

Токен создаётся в статусе active и пригоден к записи сразу же.

Процедура ротации

Ротируйте токены раз в 90 дней или при любой кадровой смене в команде, держащей секрет. Порядок — создать → переключить → отозвать, никогда наоборот. Если сначала отозвать — коннектор ослепнет до момента переключения.

По шагам

1. Создайте новый токен с той же привязкой индекса. Назовите по дате ротации (bitrix-prod-2025-04).
2. Раскатайте новый токен на каждый инстанс CMS, пишущий в этот индекс:
   • PrestaShop: вставьте в настройках модуля, сохраните, нажмите Test connection.
   • Bitrix: обновите параметр модуля через админку или PHP-конфиг; перезагрузите.
   • WordPress: обновите поле AACsearch → Settings; запустите wp aacsearch diagnose.
   • Серверный коннектор Shopify-стиля: обновите env-переменную AACSEARCH_CONNECTOR_TOKEN; перезапустите сервис.
   • Strapi: обновите конфиг плагина в admin или config/plugins.{js,ts}; перезапустите Strapi.
3. Подтвердите, что используется новый токен:
   • В панели смотрите, как lastUsedAt нового токена сдвигается вперёд.
   • lastUsedAt старого токена замирает.
   • В Connectors → Sync history свежие задачи указывают на лейбл нового токена.
4. Подождите минимум 24 часа с двумя активными токенами одновременно. Это ловит инстансы, которые забыли обновить (cron, вторичные серверы, фоновые воркеры).
5. Отзовите старый токен в Панель → Connectors → [токен] → Revoke. Отзыв применяется немедленно.
6. Убедитесь, что от старого токена больше нет запросов (его lastUsedAt замер). Если всплыл скрытый клиент — следующий вызов вернёт 403 invalid_or_revoked_key, и оператор может либо выпустить новый токен, либо расследовать источник.

Почему два токена одновременно

Несколько ss_connector_* токенов могут существовать для одного индекса. Это независимые строки в SearchApiKey. На этом построена zero-downtime ротация: старый токен продолжает работать, пока новый раскатывается.

Отзыв токена

Используйте revoke, когда:

• Ротация завершена, старый токен больше не используется.
• Токен утёк (попал на скриншот, случайно закоммичен в git, отправлен по небезопасному каналу).
• Инстанс CMS списан.

Отзыв применяется немедленно и необратимо. «Undo» нет. Следующий вызов отозванным токеном возвращает:

{ "error": "invalid_or_revoked_key" }

с HTTP 403. Текущие в полёте запросы падают; повторы на стороне CMS будут ловить тот же 403, пока оператор не выпустит новый токен и не раскатит его.

Реакция на утечку

Если есть подозрение на утечку токена, порядок действий:

1. Сразу отзовите в панели. Не ждите — стоимость временной деградации ниже, чем стоимость записей атакующего.
2. Выпустите новый токен для того же индекса. Раскатите по процедуре выше.
3. Проаудитьте индекс на неожиданные записи:
   • Панель → Connectors → Sync history — фильтр по дате, ищите незнакомые батчи.
   • Проверьте индекс на документы с непривычными паттернами external_id.
4. Проаудитьте downstream — если тот же токен переиспользовался для других индексов (так делать не нужно — один токен на индекс), отзовите и пересоздайте и их.
5. Проротируйте канал, через который утечка произошла: смените пароль на shared-документе, форс-ротация CI-секрета и т.д.

Connector API не даёт чтения — утёкший connector-токен не может выкачать документы, данные клиентов или аналитику. Он может только писать мусор в привязанный индекс. Отзыв закрывает эту дыру быстро.

Гигиена области действия

connector_write — единственная область, которая нужна CMS-модулю. UI панели выдаёт connector-токены только с этой областью, API отбрасывает любую более широкую область при создании.

Не переиспользуйте connector-токен как search-токен. Разные surface-ы:

Перемешивание ломает обе половины модели безопасности: search-токен в CMS потеряет доступ на запись; connector-токен в браузере раскроет write-credentials каждому посетителю.

Токены под каждое окружение

Один токен на одно окружение:

• bitrix-staging — staging-инстанс Bitrix
• bitrix-prod — продовый инстанс Bitrix
• bitrix-disaster-recovery — резервный standby, если он есть

При выводе окружения из эксплуатации сначала отзовите его токен, потом сворачивайте инфраструктуру. Токены, пережившие свой инстанс CMS, — самая частая причина «призрачных записей» в аудитах.

Программная ротация

Если оператор хочет автоматизировать цикл ротации:

• POST /api/v1/keys — создать новый connector-токен (требуется admin-аутентификация, область connector_write).
• DELETE /api/v1/keys/:id — отозвать токен по ID.
• GET /api/v1/keys?prefix=ss_connector_ — список активных connector-токенов.

См. v1 REST API. Те же oRPC-процедуры (search.createConnectorToken, search.revokeApiKey) лежат под dashboard'ом — любая плановая ротация должна звать v1-эндпоинты, а не парсить админку.

Связанные страницы

• Обзор коннекторов
• Жизненный цикл Connector API
• Диагностика — в т.ч. как отозванные токены проявляются в ошибках
• Custom Connector