Custom Universal Connectors
On a development machine, you can develop an AutoIt script that will launch and authenticate to your application for your connection component.
Check out the Universal Connectors available for download from the CyberArk Marketplace |
We strongly recommend using a separate development machine to develop your AutoIt scripts.
Download and install AutoIt3 on the development machine to develop PSM universal connector components.
By default, AutoIt3 is installed in the following location on your computer: %ProgramFiles%\AutoIt3.
When using Autoit based connection components, we recommend that you compile the Autoit script to an executable form and use that binary. Running AutoIt scripts directly using AutoIt3.exe might introduce security risks.
-
Install the application to integrate on your development machine.
-
In the Components subfolder of the PSM installation folder, copy PSMAutoItDispatcherSkeleton.au3 to your development environment and rename it, but do not change the .au3 extension.
-
Open the new .au3 file and change the code contained in it, as follows:
Code
Edit
;CHANGE_ME
Replace each of the ";CHANGE_ME" comments with your own code/constants.
$CLIENT_EXECUTABLE
Specify the path of the application to execute.
Main() function
Replace the "Handle login here! comment" with the logic that handles the login using the PSM Universal Connector API. For more information about this API, see the Custom Universal Connectors.
-
Debug and test the AutoIt script using the Generic Client Driver supplied by CyberArk, as follows:
-
Copy the following files from the PSM\Components folder on the PSM machine to the same folder of the new au3 script on your development workstation:
-
PSMGenericClientDriver.dll
-
PSMGenericClientDriver.xml
- PSMGenericClientWrapper.au3
-
-
In the PSMGenericClientDriver.xml file, update the SessionProperties section and specify values that you will use to test connections using your application.
The following sample shows a typical PSMGenericClientDriver.xml file that specifies the functions to check and the session properties to return.
<?xml version="1.0" encoding="utf-8" ?>
<PSMGenericClientDriver>
<Functions>
<Function Name="SendPID" Return="Success" />
<Function Name="MapTSDrives" Return="Success" />
<Function Name="GetSessionPropertyBufferLength" Return="Success" />
<Function Name="GetSessionProperty" Return="Success" />
<Function Name="LogWrite" Return="Success" />
</Functions>
<SessionProperties>
<SessionProperty Name="SessionUUID" Value="0b4d3135-d824-4044-8a3f-555a72b72577" />
<SessionProperty Name="Username" Value="administrator" />
<SessionProperty Name="Address" Value="10.10.10.10" />
<SessionProperty Name="Password" Value="very-secured-pass" />
</SessionProperties>
</PSMGenericClientDriver> - Run the test driver, using the following command:
C:\<path>\autoit3.exe <your-script.au3> "c:\<Folder of the new au3 script> \" /test
In the command above, the second parameter specifies the path to the folder that contains the driver’s dll. This parameter must end with a backslash.
-
The file PSMGenericClientDriver.txt will be created and will include the log output of the script.
-
-
To prevent hiding the main application window, thus causing the session not to be recorded, you must provide the title and class name of that window to the PSM Administrator. The Administrator will use this information when configuring PSM to support the new PSM Universal Connector connection component.
The PSM Universal Connector API is used from within the AutoIt script to integrate with the PSM environment, and obtain information such as the session properties (e.g. address/user/password) that PSM provides to the script.
The following PSMDispatcherUtilsWrapper functions enable you to create the AutoIt wrapper:
Description |
This function initializes PSM’s dispatcher API library. It must be called once at the beginning of the AutoIt script implementation (before any other API calls). |
Parameters |
This function accepts no parameters. |
Return values |
$PSM_ERROR_SUCCESS – Indicates that the API library was initialized successfully. Any other return value means that an error occurred. For more details, use PSMDispatcherUtilsWrapper_PSMGetLastErrorString. |
Description |
This function terminates PSM’s dispatcher API library. It must be called once after the AutoIt script finishes using the PSM API functions in order to free consumed resources. |
Parameters |
This function accepts no parameters. |
Return values |
This function has no return values. |
Description |
This function checks if the API library is currently loaded. |
||||||
Parameters |
This function accepts no parameters. |
||||||
Return values |
|
Description |
This function returns a description of the last error that occurred in prior PSM library API calls. |
Parameters |
This function accepts no parameters. |
Return values |
A string that describes the last error that occurred. |
Parameters |
This function has two parameters:
|
||||||||||||
Return values |
Any other return value means that an error occurred. For more details, use PSMDispatcherUtilsWrapper_PSMGetLastErrorString. |
Description |
This function reports the PID of the connection client started by the dispatcher to the PSM server, after which PSM starts monitoring the connection client and allows user input. If the function is not called, the session will be stopped as soon as the dispatcher exits. |
|||
Parameters |
$PID - The process ID to send to the PSM server |
|||
Return values |
Any other return value means that an error occurred. For more details, use PSMDispatcherUtilsWrapper_PSMGetLastErrorString. |
Description |
This function is used to enable RDP local drive mapping for connection clients that do not support “Windows Shell Extensions”. When the system detects that a session has mapped local drives, it adds shortcuts to these drives in the computer’s Explorer window. If the connection client application does not display the Windows’ standard File Open/Save windows, these drives won’t appear anywhere. In these cases, the MapTSDrives will actually allocate drive letters for the mapped drives so that the drives will appear in any kind of File Open/Save windows. |
|||
Parameters |
This function accepts no parameters. |
|||
Return values |
Any other return value means that an error occurred. For more details, use PSMDispatcherUtilsWrapper_PSMGetLastErrorString |
Description |
This function retrieves a session property (address/user/password) from PSM by passing the property's name as a parameter. |
||||||
Parameters |
|
||||||
Return values |
Any other return value means that an error occurred. For more details, use PSMDispatcherUtilsWrapper_PSMGetLastErrorString. |
During PSM installation, the following files are copied to the Components subfolder of the PSM installation folder:
File |
Description |
---|---|
PSMConnectorPackageSample.zip |
A sample connector package you can use to create your own Universal Connector. This file is a sample package for the PSM Universal Connector for connecting to the server over the VNC protocol:
|
PSMRealVNCDispatcher.au3 |
A sample AutoIt script of the PSM Universal Connector connection component for connecting to server over the VNC protocol. This sample is also created as a sample connection component in the PVWA. |
PSMAutoItDispatcherSkeleton.au3 |
The basic AutoIt script file. This file contains a skeleton script for the PSM Universal Connector connection component. You can copy this script and customize it. |
PSMGenericClientWrapper.au3 |
An AutoIt script that contains the API functions required for the PSM Universal Connector connection component. Do not modify this file. |
|
Files that comprise a driver that enables you to test your customized connection component: |
Compile an executable ( .exe) from your .au3 file, and test it.
Create a zip archive file containing:
- The universal connector executable you created in the step above.
- Any additional files needed for the universal connector to run, such as .dlls or .exes.
-
A package.json file specifying a path to each application you want to run so that it will be opened in AppLocker. This enables the universal connector to run on the PSM machine.
Do not place the executable directly under c:\ . Place the executable in a new subfolder.
{ "PackageName": "PSMRealVNCDispatcherSample", "ClientAppPaths":[ { "Path":"C:\<New subfolder>\VNC-Viewer-5.0.5-Windows-64bit.exe" } ] }
The following special characters are not supported in the package: [ ]
The package.json file must appear at the root of the zip archive.
-
The PSMDispatcherUtils.dll file.
Copy it from the PSM\Components folder.
Default: C:\Program Files (x86)\CyberArk\PSM\Components
You can find a sample PSMRealVNCDispatcherSample.zip located PSM\Components including a readme.txt file with deployment documentation. Use this sample file as a reference when creating a package.
■ | Make sure that the password used by the PSM Universal Connector connection client cannot be exposed to the user interface. |
■ | Make sure that sensitive data will not be saved to the disk during the session; in case some data is saved, consider cleaning this data as part of the AutoIt script. |
■ | PSM provides the ability to block any user interaction that may interfere with the login procedure. When the login procedure of the Universal Connector connection component starts, PSM prevents the user from typing keystrokes or using the mouse until it receives an indication from the SendPID function that the login procedure is completed. Make sure that the SendPID function is called only after the login procedure is completed. For more information, see SendPID. |
If your Universal Connector connection component requires user input during login, you can disable this block by adding the client specific parameter BlockUserInput. For details, see Configure a Custom Universal Connector.
For details about deploying and configuring the Universal Connector, see Deploy Universal Connectors on multiple PSM servers and Configure a Custom Universal Connector.