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

Integration Secrets: централизованное администрирование секретов интеграций

Платформа поддерживает централизованное хранение секретов интеграций в модуле Integration Secrets. Секрет идентифицируется по ключу serviceKey и содержит произвольный payload — набор пар «имя поля → значение», например Login, Password, ApiKey, AccessToken и другие поля, необходимые для конкретной интеграции.

Доступ

Административное управление секретами выполняется через Admin API api/admin/secrets. Доступ к этому API имеют только пользователи с ролью god-admin. Для остальных пользователей запросы к этим endpoint завершаются отказом в доступе.

Структура сущности

Каждый секрет имеет:

  • serviceKey — уникальный строковый ключ (идентификатор секрета).
  • displayName — отображаемое имя (обязательно, ограничено по длине).
  • payload — набор пар «имя поля → значение»; например Login, Password, ApiKey, AccessToken, ExpiresAt, Custom.

Значения payload хранятся в зашифрованном виде. В списковых и карточных ответах платформа возвращает только имена полей (payloadKeys), но не их содержимое.

Операции Admin API

Через api/admin/secrets доступны следующие операции:

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

Разделение метаданных и значений секрета

В списковых и карточных методах платформа не возвращает реальные значения секрета. Вместо содержимого payload в ответах передаются только имена полей (payloadKeys). Это позволяет администратору видеть структуру секрета без раскрытия чувствительных данных.

Чтобы получить реальные значения полей, используется отдельный endpoint просмотра payload. Такой вызов считается чувствительной операцией и должен использоваться только при необходимости явной проверки или диагностики секрета.

Контракты payload

Для части сервисов используются заранее зарегистрированные контракты payload. Контракт описывает:

  • префикс serviceKey;
  • тип контракта;
  • разрешённые поля payload.

Примеры зарезервированных префиксов: ldap, openldap, radius, diadoc, sbis, ews, oauth, cryptopro-dss, azure-cognitive, pt-sandbox, multifactor, kontur-kedo, jitsi.

Администратор может получить контракт как для конкретного ключа, так и список всех зарегистрированных контрактов. Это позволяет заранее понять, какие поля допустимо сохранять для конкретной интеграции.

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

Валидация данных секрета

При создании и обновлении секрета платформа валидирует:

  • serviceKey — должен соответствовать допустимому формату ключа;
  • displayName — обязателен и ограничен по длине;
  • payload — должен быть непустым объектом.

Для зарезервированных ключей дополнительно проверяется соответствие payload зарегистрированному контракту.

Удаление секрета

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

Аудит обращений

Операции работы с секретами фиксируются в журнале аудита. Для каждой записи сохраняются:

  • ключ секрета (serviceKey);
  • тип действия;
  • пользователь, выполнивший действие;
  • момент выполнения;
  • IP-адрес;
  • источник вызова.

Для административных запросов в аудите используется источник adminApi. Отдельно доступны:

  • просмотр аудита по конкретному serviceKey;
  • просмотр общего аудита по всем секретам с фильтрами по периоду, действию, пользователю и ключу секрета.

Это позволяет контролировать не только изменение секретов, но и факты просмотра их содержимого.

Admin API разделяет просмотр структуры и просмотр содержимого секрета. Списковые и карточечные методы возвращают только метаданные и payloadKeys — имена полей payload без значений. Расшифрованные значения доступны только через отдельный endpoint просмотра payload. Каждый такой вызов фиксируется в журнале аудита как операция чтения секрета. Аналогично аудит пишется при создании, обновлении и деактивации записи.

Совместимость с legacy-настройками и порядок чтения

Серверные компоненты платформы получают секреты интеграций через единый read-only фасад ISecretsProvider.

Порядок разрешения секрета:

  1. Сначала выполняется поиск по serviceKey в новом хранилище IntegrationSecrets.
  2. Если запись в новом хранилище отсутствует, платформа использует fallback к legacy-источникам настроек и таблицам *Credentials / *Settings.
  3. Если секрет найден в IntegrationSecrets, он имеет приоритет над legacy-значением.

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

Провайдер ISecretsProvider предназначен только для чтения секретов. Создание, обновление и удаление записей выполняется через Admin API (см. выше).

Практически это означает, что при миграции интеграции администратору достаточно создать запись в IntegrationSecrets с корректным serviceKey: после этого чтение секрета начнёт выполняться из нового хранилища автоматически, без изменения потребителей, которые уже работают через ISecretsProvider.

Работа с секретами из смарт-скриптов

В серверных смарт-скриптах секреты читаются через объект UTILS:

// JavaScript
var apiKey = UTILS.getsecretvalue("dadata-5", "ApiKey");
var creds  = UTILS.getsecretpayload("sbis-3");

-- Lua
local apiKey = UTILS:getsecretvalue("dadata-5", "ApiKey")
local creds  = UTILS:getsecretpayload("sbis-3")
  • getsecretvalue(serviceKey, fieldName) — одно поле из payload.
  • getsecretpayload(serviceKey) — весь payload целиком.
  • Если секрет или поле не найдены — возвращается null, HTTP 500 не возникает.
  • Каждое обращение фиксируется в журнале аудита с источником smartScript.

Запись секретов из смарт-скриптов:

// JavaScript
UTILS.set_secret_value("passwork", "accessToken", newToken);
UTILS.set_secret_payload("sbis-3", {accessToken: newToken, refreshToken: newRefresh});

-- Lua
UTILS:set_secret_value("passwork", "accessToken", newToken)
UTILS:set_secret_payload("sbis-3", {accessToken = newToken, refreshToken = newRefresh})
  • set_secret_value(serviceKey, fieldName, value) — обновляет одно поле секрета (upsert).
  • set_secret_payload(serviceKey, payload) — записывает payload целиком (upsert).
  • Запись фиксируется в журнале аудита с источником smartScript.

Подробнее о методах UTILS — на странице Смарт-скрипты.

Практический смысл для администратора

Integration Secrets позволяют централизованно управлять секретами внешних сервисов без перехода в отдельные настройки каждой интеграции. При этом платформа специально разделяет просмотр структуры секрета и просмотр его фактических значений, чтобы снизить риск случайной утечки чувствительных данных и обеспечить полноценный audit trail.