Connector Creation Tool Usage

Connector Creation Tool (CCT) is a command-line utility for creating and debugging custom service connection types. The archive created with this utility is loaded into PAM in the Configuration → Service Connection section.

Prerequisites

There are no additional requirements to run on Windows.
To run on Linux, you need to have Microsoft .NET Core 8 and Docker installed.

Connector Development

1. To make it easier to work with the Connector Creation Tool (CCT), add an alias for it using the command below. Before running the command, replace <path to CCT> with the location on the file system where you have the Connector Creation Tool.

   After executing the command below, close the terminal and open it again.

   Windows

   Adding the path to CCT to the environment variable

   "New-Alias cct <path to CCT>\Pam.Tools.ConnectorCreationTool.exe" | Add-Content $PROFILE

   Linux

   Adding the path to CCT to the environment variable

   echo 'alias cct="<path to CCT>/run-cct.sh"' >> ~/.bashrc

2. Create a folder for the connector and navigate to it:

   Connector Folder Creation

   mkdir my_connector
   cd my_connector

3. Create a connector template using the new command:

   Connector Template Creation

   cct new

   The connector type is selected depending on the OS: ps1 for Windows, sh for Linux. If necessary, you can change the type in the options of the new command, for more information see the command reference.

   After executing the command, the main files of the connector will appear in the directory. For more information, see connector structure.

4. The connector.ps1/sh file contains methods that need to be implemented. Initially such methods return an error when called, but the file also contains working examples in commented code. Implement these methods.

   info

   The main script of the connector must be written in bash or powershell, depending on the selected connector type. At the same time, to implement the methods, you can use any languages and technologies, depending on what is more convenient to access the resource. In this case, you will need to call your scripts or executables created in other languages ​​in the main connector.ps1/sh script.

5. Go to connector debugging.

Connector Debugging

Once the methods in the script are implemented, you can check their execution using the run command. For more information on the run command, see the command reference.

1. Check the connection to the connector.

   Checking the connection to the connector

   cct run test_connection -a <DNS or IP of the connector>

2. Check the command of setting the password for the user.

   Setting the password for the user

   cct run set_user_password -a <DNS or IP of the connector> --user <user> --new-password <new password>

3. Check the command of setting the key for the user.

   Setting the key for the user

   cct run set_user_key -a <DNS or IP of the connector> --user <user> --old-key-path <old key path> --new-key-path <new key path>

4. Check the user password verification command.

   User password verification

   cct run test_password -a <DNS or IP of the connector> --user <user> --password <password>

5. Check the user key verification command.

   User key verification

   cct run test_key -a <DNS or IP of the connector> --user <user> --key-path <key path>

6. Check the command of checking for unmanaged keys.

   Checking for unmanaged keys

   cct run test_unmanaged_keys -a <DNS or IP of the connector> --user <user> --key-path <key path>

7. Check the unmanaged key removal command.

   Removing unmanaged keys

   cct run remove_unmanaged_keys -a <DNS or IP of the connector> --key-path <key path>

8. Check the command of getting information about a resource.

   Getting information about a resource

   cct run get_resource_info -a <DNS or IP of the connector>

9. Check the command of getting information about an account.

   Getting information about an account

   cct run get_account_info -a <DNS or IP of the connector> --user <user>

10. Check the command of getting the list of users.

    Getting a list of users

    cct run get_users -a <DNS or IP of the connector>

11. After checking all service operations, go to packing the connector.

Connector Packing

Connector files need to be packed into a ZIP archive for further uploading into PAM. To do this, run the following command in the same directory:

Connector packing

cct pack

For more information on the pack command, see the command reference.

ZIP archive will be placed to the parent directory. Next, go to PAM in the Configuration → Service connection section to upload the ZIP archive file of the connector.

Connector Structure

There are three main files in the ZIP archive file of the connector:

• info.json—connector metadata
• info.schema.json—JSON schema of info.json file
• connector.ps1/sh—script performing service operations

In addition to the main files, the connector may contain any other files, including binary ones. Except for files named wrapper.ps1 and wrapper.sh. These file names are reserved for PAM for an additional script to start the connector.

The maximum size of the ZIP archive file of the connector is 100 MB.

Example of info.json file

{
  "$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 schema file name.
• Id—connector identifier, must be unique within PAM installation.
• Name—connector name that will be displayed in PAM, must be unique within PAM installation.
• Description—description of the connector that can be viewed in the connector details in PAM. Optional.
• Version—connector version.
• CreatedAt—connector creation time, specified automatically when packaging the connector.
• ConnectorType—connector type (sh or ps1).
• ScriptTimeout—timeout for attempting to perform a service operation by the connector in seconds. If the script does not complete within the specified time during the execution of a service operation, the operation will time out.
• IsKeyServiceOperationSupported—flag indicating whether the connector supports working with SSH keys. If the script implements operations with SSH keys, then specify true.
• LinuxSandbox—optional section. Contains settings to override the default Docker sandbox settings specified in Core/appsettings.json.
• Image—Docker image tag for sandbox execution.
• CpuLimit—CPU limit of one sandbox container.
• MemoryLimitMb—memory limit of one sandbox container.
• StorageLimitMb—temporary storage limit of one sandbox container.
• PidCountLimit—number of processes limit of one sandbox container.

info

There is no sandbox for PowerShell connectors.

Command Reference

new

Creates a template for a new connector. This command creates info.json, info.schema.json and connector.ps1/sh files in the specified directory.

Windows

Example

<path to CCT>\Pam.Tools.ConnectorCreationTool.exe new -t ps1 -p C:\Users\user\documents\folder1\

Linux

Example

bash <path to CCT>/run-cct.sh new -t ps1 -p /home/user/documents/folder1/

Parameters of the command new

Parameter	Required	Description
-v, --verbose	—	Enable display of additional logs.
-p, --path path	—	Path to the directory where the info.json, info.schema.json and connector.ps1/sh files will be created. If not specified, the files will be created in the current folder.
-t, --type type	—	Script type. Possible values: sh, ps1. sh — only run on Linux (bash) ps1 — only run on Windows (powershell)
-h, --help	—	Usage information and help.

pack

Creates a ZIP archive of the connector for further uploading into PAM.

Windows

Example

<path to CCT>\Pam.Tools.ConnectorCreationTool.exe pack -p C:\Users\user\documents\folder1\ -n b80d094b715aa08375b87e9.1.1

Linux

Example

bash <path to CCT>/run-cct.sh pack -p /home/user/documents/folder1/ -n b80d094b715aa08375b87e9.1.1

Parameters of the command pack

Parameter	Required	Description
-v, --verbose	—	Enable display of additional logs.
-p, --path path	—	Path to the connector.
-n, --name name	—	The name of the ZIP file without the .zip extension. By default, the name consists of the values ​​of the ID and Version fields of the info.json file.
-h, --help	—	Usage information and help.

hash

Calculates the SHA-256 hash of a file. Used to ensure file integrity.

Windows

Example

<path to CCT>\Pam.Tools.ConnectorCreationTool.exe hash -p C:\Users\user\documents\folder1\

Linux

Example

bash <path to CCT>/run-cct.sh hash -p /home/user/documents/folder1/

Parameters of the command hash

Parameter	Required	Description
-v, --verbose	—	Enable display of additional logs.
-p, --path path	Yes	Path to the connector (ZIP archive).
-h, --help	—	Usage information and help.

run

Launches the connector, executes the connector script in the specified directory.

Windows

Example

<path to CCT>\Pam.Tools.ConnectorCreationTool.exe run test_connection -p C:\Users\user\documents\folder1\ -a 192.168.5.1

Linux

Example

bash <path to CCT>/run-cct.sh run test_connection -p /home/user/documents/folder1/ -a 192.168.5.1

Parameters of the command run

Parameter	Required	Description
-v, --verbose	—	Enable display of additional logs.
-p, --path	—	Path to the connector (ZIP archive or directory).
-a, --address address	Yes	DNS or IP of the connector.
--port port	—	Connector port.
-sa, --service-account account	—	Service account name.
-sp, --service-account-password password	—	Service account password.
-skp, --service-account-key-path key-path	—	service account key path.
-slt, --service-account-location-type location-type	—	Service account location type. Possible values: Domain, Local.
--disable-sandbox	—	Disable sandbox.
-h, --help	—	Usage information and help.

Commands that can be launched with run command

Command	Description
test_connection	Check the connection to the connector.
set_user_password	Set a password for the user.
set_user_key	Set a key for the user.
test_password	Check user password.
test_key	Check user key.
test_unmanaged_keys	Check for unmanaged keys.
remove_unmanaged_keys	Remove unmanaged keys.
get_resource_info	Get information about a resource.
get_account_info	Get information about an account.
get_users	Get a list of users.