Работа с Connector Creation Tool

Connector Creation Tool (CCT) — это утилита командной строки для создания и отладки собственных типов сервисного подключения. Созданный с помощью этой утилиты архив загружается в PAM в разделе Конфигурация → Сервисное подключение.

Предварительные требования

Для запуска на Windows нет дополнительных требований.
Для запуска на Linux требуется наличие установленных Microsoft .NET Core 8 и Docker.

Подготовка коннектора

1. Для удобства работы с утилитой Connector Creation Tool (CCT) добавьте для нее псевдоним с помощью команды, указанной ниже. Перед выполнением команды замените <путь до CCT> на то расположение в файловой системе, по которому у вас находится Connector Creation Tool.

   После выполнения указанной команды закройте терминал и откройте заново.

   Windows

   Добавление пути до CCT в переменную окружения

   "New-Alias cct <путь до CCT>\Pam.Tools.ConnectorCreationTool.exe" | Add-Content $PROFILE

   Linux

   Добавление пути до CCT в переменную окружения

   echo 'alias cct="<путь до CCT>/run-cct.sh"' >> ~/.bashrc

2. Создайте папку для коннектора и перейдите в нее:

   Создание папки для коннектора

   mkdir my_connector
   cd my_connector

3. Создайте шаблон коннектора с помощью команды new:

   Создание шаблона коннектора

   cct new

   Тип коннектора выбирается в зависимости от ОС: на Windows — ps1, на Linux — sh. При необходимости можно поменять тип в опциях команды new, подробную информацию смотрите в справочнике команд.

   После выполнения команды в директории появятся основные файлы коннектора. Подробную информацию смотрите в пункте структура коннектора.

4. В файле connector.ps1/sh по умолчанию есть методы, которые требуется реализовать. Изначально они возвращают ошибку и содержат закомментированные примеры с корректно возвращаемыми данными. Реализуйте эти методы.

   Информация

   Основной скрипт коннектора должен быть написан на языке bash или powershell, в зависимости от выбранного типа коннектора. При этом для реализации методов можно использовать любые языки и технологии, в зависимости от того, на чем удобнее делать обращения к ресурсу. В этом случае понадобится в основном скрипте connector.ps1/sh вызывать ваши скрипты или исполняемые файлы, созданные на других языках.

5. Переходите к отладке коннектора.

Отладка коннектора

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

1. Проверьте соединение до коннектора.

   Проверка соединения до коннектора

   cct run test_connection -a <DNS или IP коннектора>

2. Проверьте команду установки пароля для пользователя.

   Установка пароля для пользователя

   cct run set_user_password -a <DNS или IP коннектора> --user <пользователь> --new-password <новый пароль>

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

   Установка ключа для пользователя

   cct run set_user_key -a <DNS или IP коннектора> --user <пользователь> --old-key-path <старый ключ> --new-key-path <новый ключ>

4. Проверьте команду проверки пароля пользователя.

   Проверка пароля пользователя

   cct run test_password -a <DNS или IP коннектора> --user <пользователь> --password <пароль>

5. Проверьте команду проверки ключа пользователя.

   Проверка ключа пользователя

   cct run test_key -a <DNS или IP коннектора> --user <пользователь> --key-path <ключ>

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

   Проверка наличия неуправляемых ключей

   cct run test_unmanaged_keys -a <DNS или IP коннектора> --user <пользователь> --key-path <ключ>

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

   Удаление неуправляемых пользователем ключей

   cct run remove_unmanaged_keys -a <DNS или IP коннектора> --key-path <ключ>

8. Проверьте команду получения информации о ресурсе.

   Получение информации о ресурсе

   cct run get_resource_info -a <DNS или IP коннектора>

9. Проверьте команду получения информации об аккаунте.

   Получение информации об аккаунте

   cct run get_account_info -a <DNS или IP коннектора> --user <пользователь>

10. Проверьте команду получения списка пользователей.

    Получение списка пользователей

    cct run get_users -a <DNS или IP коннектора>

11. После проверки всех сервисных операций переходите к упаковке коннектора.

Упаковка коннектора

Проверенные файлы коннектора требуется упаковать в ZIP-архив для его дальнейшей загрузки в PAM. Для этого выполните следующую команду в той же директории:

Упаковка коннектора

cct pack

Подробную информацию о команде pack смотрите в справочнике команд.

Готовый ZIP-архив будет записан в родительскую директорию. Далее переходите в PAM в раздел Конфигурация → Сервисное подключение для загрузки ZIP-архива коннектора.

Структура коннектора

В ZIP-архиве коннектора есть три основных файла:

• info.json — метаданные коннектора
• info.schema.json — JSON-схема файла info.json
• connector.ps1/sh — скрипт, выполняющий сервисные операции

Кроме основных файлов коннектор может содержать любые другие файлы, в том числе бинарные, кроме файлов с именем wrapper.ps1 и wrapper.sh Эти имена файлов зарезервированы под PAM для вспомогательного скрипта для запуска коннектора.

Максимальный размер ZIP-архива коннектора — 100 МБ.

Пример файла info.json

{
  "$schema": "info.schema.json",
  "Id": "TestBashConnector",
  "Name": "Test Bash connector",
  "Description": "This is a test connector",
  "Version": "1.0",
  "CreatedAt": "2024-12-05 14:45:03Z",
  "ConnectorType": "sh",
  "ScriptTimeout": 30,
  "IsKeyServiceOperationSupported": false,
  "LinuxSandbox": {
    "Image": "my-test-connector:1.0",
    "CpuLimit": "0.5",
    "MemoryLimitMb": "512",
    "StorageLimitMb": "1024",
    "PidCountLimit": "8"
  }
}

• $schema — имя файла JSON-схемы.
• Id — идентификатор коннектора, должен быть уникальным в рамках PAM.
• Name — имя коннектора, которое будет отображаться в PAM, должно быть уникальным в рамках PAM.
• Description — описание коннектора, которое можно будет просмотреть в деталях коннектора в PAM. Опциональное поле.
• Version — версия коннектора.
• CreatedAt — время создания коннектора, указывается автоматически при упаковке коннектора.
• ConnectorType — тип коннектора (sh или ps1).
• ScriptTimeout — таймаут работы коннектора в секундах. Если при выполнении сервисной операции скрипт не завершится за указанное время, то операция завершится по таймауту.
• IsKeyServiceOperationSupported — флаг, показывающий, поддерживается ли коннектором работа с SSH-ключами. Если в скрипте реализованы операции с SSH-ключами, то укажите true.
• LinuxSandbox — опциональный раздел. Содержит настройки для переопределения настроек по умолчанию Docker-песочницы, указанных в Core/appsettings.json.
• Image — тег Docker-образа для выполнения песочницы.
• CpuLimit — ограничение работы CPU одного контейнера песочницы.
• MemoryLimitMb — ограничение работы по памяти одного контейнера песочницы.
• StorageLimitMb — ограничение временного хранилища одного контейнера песочницы.
• PidCountLimit — ограничение количества процессов одного контейнера песочницы.

Информация

Для PowerShell-коннекторов песочницы нет.

Справочник команд

new

Создает шаблон для нового коннектора. Данная команда генерирует файлы info.json, info.schema.json и connector.ps1/sh в указанной директории.

Windows

Пример запуска команды

<путь до CCT>\Pam.Tools.ConnectorCreationTool.exe new -t ps1 -p C:\Users\user\documents\folder1\

Linux

Пример запуска команды

bash <путь до CCT>/run-cct.sh new -t ps1 -p /home/user/documents/folder1/

Параметры команды new

Имя	Обязательный	Описание
-v, --verbose	—	Включить показ дополнительных логов.
-p, --path path	—	Путь до каталога, в котором будут созданы файлы info.json и connector.ps1. Если не указан, то файлы будут созданы в текущей папке.
-t, --type type	—	Тип скрипта коннектора. Возможные значения: sh, ps1. sh — выполняются только на Linux (bash) ps1 — выполняются только на Windows (powershell)
-h, --help	—	Информация об использовании и помощь.

pack

Создает ZIP-архив коннектора для последующей загрузки в консоли администратора.

Windows

Пример запуска команды

<путь до CCT>\Pam.Tools.ConnectorCreationTool.exe pack -p C:\Users\user\documents\folder1\ -n b80d094b715aa08375b87e9.1.1

Linux

Пример запуска команды

bash <путь до CCT>/run-cct.sh pack -p /home/user/documents/folder1/ -n b80d094b715aa08375b87e9.1.1

Параметры команды pack

Имя	Обязательный	Описание
-v, --verbose	—	Включить показ дополнительных логов.
-p, --path path	—	Путь до коннектора.
-n, --name name	—	Имя ZIP-файла без указания расширения .zip. По умолчанию имя состоит из значений полей ID и Version файла info.json.
-h, --help	—	Информация об использовании и помощь.

hash

Рассчитывает хеш SHA-256 файла. Используется для обеспечения целостности файлов.

Windows

Пример запуска команды

<путь до CCT>\Pam.Tools.ConnectorCreationTool.exe hash -p C:\Users\user\documents\folder1\

Linux

Пример запуска команды

bash <путь до CCT>/run-cct.sh hash -p /home/user/documents/folder1/

Параметры команды hash

Имя	Обязательный	Описание
-v, --verbose	—	Включить показ дополнительных логов.
-p, --path path	Да	Путь до коннектора (ZIP-архив).
-h, --help	—	Информация об использовании и помощь.

run

Запускает коннектор, выполняет скрипт коннектора в указанной директории.

Windows

Пример запуска команды

<путь до CCT>\Pam.Tools.ConnectorCreationTool.exe run test_connection -p C:\Users\user\documents\folder1\ -a 192.168.5.1

Linux

Пример запуска команды

bash <путь до CCT>/run-cct.sh run test_connection -p /home/user/documents/folder1/ -a 192.168.5.1

Параметры команды run

Имя	Обязательный	Описание
-v, --verbose	—	Включить показ дополнительных логов.
-p, --path	—	Путь до коннектора (ZIP-архив или директория).
-a, --address address	Да	Адрес коннектора в виде DNS или IP.
--port port	—	Порт коннектора.
-sa, --service-account account	—	Имя сервисного аккаунта.
-sp, --service-account-password password	—	Пароль сервисного аккаунта.
-skp, --service-account-key-path key-path	—	Ключ сервисного аккаунта.
-slt, --service-account-location-type location-type	—	Тип нахождения сервисного аккаунта. Возможные значения: Domain, Local.
--disable-sandbox	—	Отключить песочницу.
-h, --help	—	Информация об использовании и помощь.

Команды, которые можно запускать с помощью run

Имя	Описание
test_connection	Проверить соединение до коннектора.
set_user_password	Установить пароль для пользователя.
set_user_key	Установить ключ для пользователя.
test_password	Проверить пароль пользователя.
test_key	Проверить ключ пользователя.
test_unmanaged_keys	Проверить наличие неуправляемых ключей.
remove_unmanaged_keys	Удалить неуправляемые пользователем ключи.
get_resource_info	Получить информацию о ресурсе.
get_account_info	Получить информацию об аккаунте.
get_users	Получить список пользователей.