Разработка коннектора к хранилищу настроек

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

Полный код и описание примера см. на GitHub: SettingsExtension.

Пример рассчитан на версию Web-клиента dv6 или выше.

Перечень необходимых инструментов:

Ниже приведена инструкция по настройке Docsvision для использования хранилища секретов.

Работа с хранилищем секретов

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

Работа с внешними хранилищами секретов выполняется через подключаемые коннекторы, начиная с версий, входящих в НО 26.1. В качестве примера используется хранилище секретов OpenBao. Аналогичным образом могут быть подключены и другие.

Подключение хранилища секретов

Чтобы подключить внешнее хранилище секретов к Docsvision, в конфигурационные файлы appsettings.json основных компонентов (Сервер приложений, Web-клиент, Управление процессами, Файловый сервис, Консоль управления Docsvision) в секцию SettingsService необходимо добавить подчинённую секцию SecretStorage. Фрагмент json-схемы для настройки доступа:

{
  "DocsVision": {
    "SettingsService": {
      "SecretStorage": { (1)
        "ConnectorType": "Example.Connector, Example.Assembly", (2)
        "Settings": {
          ... (3)
        }
      }
    }
  }
}
1 SecretStorage — секция должна быть одинакова для всех компонентов, подключенных к одной Консоли управления Docsvision.
2 ConnectorType — полное имя класса коннектора, реализующего подключение внешнего источника.
3 Settings — индивидуальные настройки коннектора. Набор параметров в секции и их значения должны быть идентичными для всех компонентов, подключенных к одной Консоли управления Docsvision.

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

Набор настроек в секции Settings отличается в зависимости от типа хранилища. Может включать адрес, токен, путь, идентификатор приложения, таймаут подключения и множество других параметров. Список параметров зависит от реализации коннектора и определяется его разработчиком. Администратор заполняет их в соответствии с документацией к коннектору. Например, для OpenBao могут быть добавлены следующие настройки:

{
  "DocsVision": {
    "SettingsService": {
      "ApiKey": "anything",
      "SecretStorage": {
       "ConnectorType": "DocsVision.Settings.Extensions.OpenBao.OpenBaoSecretStorageConnector, DocsVision.Settings.Extensions.OpenBao", (1)
       "Settings": {
        "Url": "http://docsvision.example.com:8200", (2)
        "Token": "this-is-token" (3)
       }
      }
    }
  }
}
1 ConnectorType — тип коннектора к хранилищу секретов, в данном случае — OpenBao.
2 Url — адрес подключения к хранилищу.
3 Token — токен для доступа к хранилищу.

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

Одновременно допускается подключать только одно внешнее хранилище.

Чтение настроек компонентов системы

Компоненты системы (например, Web-клиент, Сервис настроек, и др.) получают настройки в следующем порядке:

  1. Переменные окружения

  2. Конфигурационный файл

  3. Сервис настроек (значение возвращается напрямую или из внешнего хранилища секретов)

Чтение значения выполняется последовательно в соответствии с указанным порядком. Если значение найдено в одном из источников, дальнейший поиск не выполняется.

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

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

Полный список настроек, записываемых в хранилище секретов

Если внешнее хранилище секретов настроено, значения следующих настроек сохраняется в него. В Сервис настроек сохраняется только указатель на секрет.

Страница настроек в Консоль управления Docsvision Настройка

Сервер приложений

Пароль системной учетной записи

API-ключ для подключения к Workflow

Строка подключения к БД в Мастере БД

Веб-клиент

Пароль системной учетной записи

Управление процессами

Пароль системной учетной записи

API-ключ

Файловый сервис

Строка подключения к БД

Домен

Пароль пользователя для подключения к LDAP-каталогам текущего домена

Расширение

Настройки расширения

Изменение и восстановление секретных настроек

Если секрет был удален, перемещен или недоступен по сохраненному в Сервисе настроек пути, компонент не cможет прочитать соответствующую настройку. Служба компонента не запускается, а причина записывается в журнал.

Чтобы восстановить настройки, выполните одно из следующих действий:
  • Восстановите секрет во внешнем хранилище по прежнему пути.

  • Заново укажите значение настройки в Консоли управления Docsvision. Новое значение будет сохранено во внешнем хранилище, а в Сервисе настроек будет сохранен указатель на него.

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

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