Механизм учётных данных позволяет безопасно хранить и использовать реквизиты доступа к внешним сервисам в действиях, источниках данных, виджетах и других компонентах Deckhouse Development Platform (DDP). Все учётные данные шифруются перед сохранением в базе данных и расшифровываются только при использовании.

Принцип работы

Типы учётных данных

Администратор платформы создаёт типы учётных данных в разделе «Администрирование» → «Учётные данные». Каждый тип имеет:

  • «Название» — отображаемое название типа.
  • «Идентификатор» — уникальный идентификатор для использования в конфигурациях.
  • «Описание» — подсказка для пользователей.

Учётные данные пользователей

Пользователи заполняют свои персональные учётные данные в разделе «Профиль» → «Учётные данные». Для каждого типа учётных данных пользователь может указать свое значение (например, токен доступа, пароль, ключ API).

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

Выбор хранилища для типа учётных данных

При создании или редактировании типа учётных данных указывается хранилище:

  • «База данных» — значения хранятся в PostgreSQL (по умолчанию).
  • Vault — значения хранятся в HashiCorp Vault или в Deckhouse Stronghold. Доступно только если в платформе включена и настроена интеграция с Vault.

Один и тот же тип учётных данных всегда использует одно выбранное хранилище. Изменить хранилище для существующего типа можно; при этом уже сохранённые учётные данные в старом хранилище не переносятся автоматически.

Хранение в базе данных

Учётные данные с типом хранилища «База данных» сохраняются в PostgreSQL. Перед сохранением значения шифруются с использованием алгоритма AES-GCM.

Параметры шифрования:

  • Алгоритм: AES-GCM.
  • Размер ключа: 16, 24 или 32 байта (128, 192 или 256 бит).
  • Размер nonce: 12 байт.
  • Ключ шифрования: задается в конфигурации DDP в поле security.secretKey.

Зашифрованные значения сохраняются в базе данных с префиксом GCM:, что позволяет системе определить метод шифрования при расшифровке.

При изменении ключа шифрования (security.secretKey) в конфигурации все текущие учётные данные станут невалидными и не смогут быть расшифрованы.

Хранение в HashiCorp Vault

Если для типа учётных данных выбрано хранилище Vault, то реквизиты пользователей сохраняются платформой в HashiCorp Vault или в Deckhouse Stronghold.

Как это устроено:

  • В Vault используется движок KV Secrets Engine v2. Путь к секретам задаётся в настройках Vault в DDP (например, secrets/data/ddp).
  • Для каждого пользователя создаётся отдельный секрет по пути {path}/credentials/{uuid_типа}/users/{uuid_пользователя}. Внутри секрета один ключ value, значение — зашифрованные учётные данные. Шифрование выполняется ключом DDP (security.secretKey).
  • Подключение к Vault выполняется по AppRole (AppRole Role ID и AppRole Secret ID). AppRole Role ID и AppRole Secret ID сохраняются в БД DDP в зашифрованном виде. Токен Vault продлевается автоматически; при сбое продления выполняется повторный вход по AppRole.

Настройка Vault в DDP:

  1. В разделе «Администрирование» → «Учётные данные» нажмите «Настройки Vault».
  2. Включите использование Vault (Включено).
  3. Заполните параметры:
    • URL — адрес сервера Vault (например, https://vault.example.com).
    • «AppRole Role ID» — идентификатор AppRole, полученный при создании роли в Vault.
    • «AppRole Secret ID» — секрет AppRole, используется вместе с Role ID для аутентификации в Vault.
    • «Путь» — путь к секретам в KV v2. Для KV v2 путь должен содержать сегмент /data/ (например, secrets/data/ddp или secrets/data/ddp/credentials). Mount (например, secrets) должен быть заранее создан в Vault; подкаталоги после data/ создаются платформой автоматически при сохранении учётных данных.
  4. Нажмите «Проверить подключение», чтобы убедиться, что DDP может аутентифицироваться и обращаться к Vault.
  5. Сохраните конфигурацию.

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

Права доступа

Для просмотра, изменения конфигурации Vault и проверки подключения требуется глобальное разрешение на редактирование типов учётных данных: edit:user-access-credentials-types.

Особенности конфигурации

  • Поддерживается только KV Secrets Engine v2. Путь в настройках должен включать /data/ (например, mount/data/подкаталог).
  • Одна конфигурация Vault на инстанс DDP: один URL, одна AppRole, один базовый путь. Все типы учётных данных с хранилищем Vault используют этот путь (подкаталоги формируются автоматически по UUID типа).
  • Очистить все сохранённые значения типа из текущего хранилища (база данных или Vault) в любой момент можно через действие «Очистить хранилище» в таблице типов учётных данных.
  • Смена ключа шифрования DDP (security.secretKey) делает нечитаемыми и учётные данные в Vault, так как значения в Vault хранятся в зашифрованном виде.

Использование учётных данных

Учётные данные расшифровываются только при необходимости их использования, непосредственно перед обращением к внешнему сервису. После использования расшифрованные значения не сохраняются в памяти дольше необходимого.

Интеграция в компоненты платформы

Действия

В конфигурации действия можно указать список требуемых учётных данных через поле «Учётные данные». Каждое учётное данное определяется:

  • «Идентификатор» — идентификатор учётного данного (соответствует идентификатору типа учётных данных).
  • «Тип учётных данных» — выбор типа учётных данных из списка.

При выполнении действия система:

  1. Определяет пользователя, от имени которого выполняется действие (инициатор или учётная запись, выбранная в поле «Учётная запись для запуска», если включена опция «Выбрать учётную запись для запуска»).
  2. Извлекает учётные данные этого пользователя из базы данных.
  3. Расшифровывает значения учётных данных.
  4. Подставляет расшифрованные значения в шаблоны конфигурации действия (URL, заголовки, тело запроса) через плейсхолдеры вида {{.credentials.идентификатор}}.

Источники данных

В конфигурации источника данных можно указать список требуемых учётных данных аналогично действиям. При синхронизации данных система:

  1. Использует учётные данные системного пользователя, указанного в конфигурации источника данных (поле «Системная учётная запись»).
  2. Извлекает и расшифровывает учётные данные системного пользователя.
  3. Подставляет значения в шаблоны запросов источника данных.

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

Виджеты

Виджеты могут использовать учётные данные для получения данных из внешних сервисов. Механизм работы аналогичен действиям:

  1. Определяется пользователь (инициатор запроса или учётная запись, выбранная в поле «Учётная запись для виджета», если включена опция «Выбрать учётную запись для виджета»).
  2. Извлекаются и расшифровываются учётные данные.
  3. Значения подставляются в конфигурацию виджета.

Проверки статуса

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

  1. Использует учётные данные системного пользователя, указанного в конфигурации правила проверки статуса (поле «Системная учётная запись»).
  2. Извлекает и расшифровывает учётные данные системного пользователя.
  3. Подставляет значения в шаблоны конфигурации правила (URL, заголовки, параметры запросов) через плейсхолдеры вида {{.credentials.идентификатор}}.

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

Внешние сервисы

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

  1. Учётные данные из конфигурации внешнего сервиса наследуются компонентом, если в его конфигурации не указаны собственные учётные данные.
  2. Приоритет имеют учётные данные, указанные непосредственно в конфигурации компонента.

Настройка

Ключ шифрования

Ключ шифрования настраивается в конфигурации DDP в секции security.secretKey:

security:
  secretKey: "your-32-byte-secret-key-here"

Требования к ключу:

  • Длина: 16, 24 или 32 байта (128, 192 или 256 бит).
  • Только печатаемые ASCII символы.
  • Не должен быть слабым или часто используемым ключом.
  • Не должен состоять из одного повторяющегося символа.

Интеграция с Vault

Подключение к HashiCorp Vault (URL, AppRole, путь к KV v2) настраивается в веб-интерфейсе в разделе «Администрирование» → «Учётные данные» → «Настройки Vault». В конфигурационном файле DDP задаётся только ключ шифрования (security.secretKey), который используется в том числе для шифрования значений, хранящихся в Vault.

Безопасность

  • Учётные данные никогда не передаются пользователю в расшифрованном виде.
  • Расшифровка происходит только непосредственно перед отправкой запроса.
  • Расшифрованные значения не логируются.