Create CPM plugins for Web applications
This topic describes how to create CPM plugins for web applications.
Prerequisites
The prerequisites for testing and running CPM plugins for web applications on the development or CPM server are:
-
A supported browser must be installed. For more information, see Supported browsers below.
-
The latest browser driver must be installed for all browsers that you use. For more information, see Supported browsers below.
For automatic updates of your installed browser versions, deploy the WebDriverUpgrader tool.
- The latest versions of Credentials Management .NET SDK and Web Application CPM Plugin Framework must be placed in the folder where the plugin will run (for CPM it is the bin folder).
-
CPM plugins require .NET Framework 4.8. If you are using an older version of the CPM, .NET Framework 4.8 must be installed on the CPM machine as well.
Supported browsers
CyberArk may choose not to provide maintenance and support services for Web applications for CPM with relation to any of the platforms and systems listed below which have reached their formal End-of-Life date, as published by their respective vendors from time to time. For more details, contact your CyberArk support representative. |
The following browsers are supported:
Browser |
Download info |
---|---|
Google Chrome (32-bit), version 100 or later |
Click here to download this version |
Microsoft Edge (32-bit), version 103 or later |
Click here to download this version |
To prevent incompatibility issues with the CPM Webapp infrastructure, with every new browser version update, make sure to also update the browser's driver with the same version. For example, when updating the Chrome browser to version 104, the Chrome driver on the server must also be updated to version 104.
Download and install the latest driver:
-
For Google Chrome, use this link to download the latest stable 32-bit (x86) driver.
-
For Microsoft Edge, use this link to download the latest stable 32-bit (x86) driver.
Copy the relevant downloaded exe file, Chromedriver.exe or msedgedriver.exe to the CPMbin folder.
Configure platforms for web applications
You can configure platforms for web applications based on a generic platform that is available in the Marketplace.
-
Download the latest Web Application CPM Plugin Framework from the Marketplace.
-
Extract the zip file that you downloaded from the Marketplace. The downloaded zip file contains a single zip file:
Plugin.WebApp.Import.Platform-vXX.X.X.X-Master.zip
This zip file contains the Generic Web App Platform with plugin files.
-
Import the platform:
-
In the PVWA, go to Administration > Platform Management, and click Import Platform.
-
Select the Plugin.WebApp.Import.Platform-vXX.X.X.X-Master.zip file that you downloaded.
-
-
Duplicate the Generic Web App platform, and change its name to the new platform.
-
Edit the WebForm settings
-
In Automatic Password Management > Additional Policy Settings, specify the following:
Name
Description
Valid Values
VerifyURL
The URL to which to connect in the Verify action.
URL
This value may include placeholders that are replaced at run-time.
ChangeURL
The URL to which to connect in the Change action.
URL
This value may include placeholders that are replaced at run-time.
ReconcileURL
The URL to which to connect in the Reconcile action.
URL
This value may include placeholders that are replaced at run-time.
WebFormFieldsFile
The name of the file that includes the logic of the actions.
File name.
File extensions must be INI.
-
-
Edit the Add webform fields file. For each action, write the name of the action (Verify, Change or Reconcile) in [ ] and below it, specify the flow that should be run in this action.
-
Edit the Platform level parameters.
In Automatic Password Management > Additional Policy Settings, specify the following:
Name
Description
Valid Values
Default
RunVerifyAfterChange
Indicates whether or not the Verify action will be run at the end of the Change action.
Yes, No
No
RunVerifyAfterReconcile
Indicates whether or not the Verify action will be run at the end of the Reconcile action.
Yes, No
No
DriverFolder
Folder where the drive is located.
Folder path
CPM Bin folder
ActionTimout
Maximum number of seconds to wait for an action to complete.
Positive number between 1-1800
10
PageLoadTimeout
Maximum number of seconds to wait for a page to load. Positive number
Positive number between 1-1800
30
Browser
The browser with which the plugin will work.
Chrome, Edge
Chrome
BrowserPath
Path to the browser exe file.
Full path
Default browser installation location
To configure a platform to work with another supported browser, change the values of Browser and BrowserPath accordingly.
-
Click OK to save the new platform configurations and return to the Platform Management page.
Create a CPM plugin for a web browser
Step 1: Create a user profile or user to run a browser
Depending on the type of environment that you have, hardened or non-hardened, to run a browser you must either create a user profile for the PluginManagerUser account or create a new local user.
Perform one of the following procedures according to the environment that you have.
To determine if the CPM environment is hardened or not, search for the specific users such as PasswordManagerUser that are created only in hardened environments. For more information on these users, see Creates Local Windows Service users and configures permissions.
When using PluginManagerUser in a hardened environment, it is necessary for PluginManagerUser to have a profile. CyberArk provides a Powershell script in the installation folder that creates a new profile folder to host the PluginManagerUser profile. This enables browsers to run on hardened CPM environments.
-
In a PowerShell window, in the CPM bin folder where the extracted CreateUserProfile.ps1 file is located, run the CreateUserProfile.ps1 script as an Administrator:
-
Enter Import-Module .\CreateUserProfile.ps1
-
Enter Create-NewProfile "PluginManagerUser"
-
The CPM service runs with a system user on non-hardened environments. The system user is a very high privilege user in Microsoft environments and cannot, per Microsoft security requirements, run the Edge browser. To run Edge, create a new user by following the instructions below. This modified user can run the CPM service and the Edge browser.
-
Create a new local user.
-
Add the following folder permissions to the newly created user:
Permission type Permissions Folders Read permissions -
Read & Execute
-
List folder content
-
Read
-
[Drive]:\Python27
-
[Drive]:\Oracle
-
[Drive]:\Program Files (x86)\CyberArk
Full permissions - Full Control
- Read & Execute
- List
- Read
- Modify
- Write
-
[Drive]:\Program Files (x86)\CyberArk\PasswordManager\Logs
-
[Drive]:\Program Files (x86)\CyberArk\PasswordManager\tmp
-
[Drive]:\Program Files (x86)\CyberArk\PasswordManager\bin
-
[Drive]:\Program Files (x86)\ CyberArk\PasswordManager\Vault
-
[Drive]:\Program Files (x86)\CyberArk\PasswordManager\Scanner\Log
Remove permissions -
[Drive]:\Program Files (x86)\CyberArk\PasswordManager\Scanner
-
-
Change the CPM (CyberArk Password Manager) Service Log on user to the newly created user:
Step 2: Add webform fields
Use webform fields to interact with DOM elements that support web actions or create conditional statements that enable you to create blocks of webform field actions.
Single webform field commands enable you to interact with DOM elements that support web actions such as input, focus on elements, iFrame, redirect and validation.
Specify the information listed below in the webform fields. Add the fields in a list of rows, using the following format:
To enter text into an input field, specify a line in the following format:
|
To use logon account parameters, this capability must be enabled. See the Configuration section to enable this capability.
-
For logon account username: {logonaccount\username}
-
For logon account password: {logonaccount\password}
Name |
Description |
Valid Values |
---|---|---|
Identifier (mandatory) |
The ID, name, class, text or xpath of the field. |
The entry cannot contain white spaces for ID, name, or class. |
Value (mandatory) |
The value of the identifier. |
Value to enter in the field, where { } are replaced by parameters. For example, {username}@{domain} |
Type |
The type of field in the HTML page. |
ID/Name/Class/Text/XPath By default, fields are searched in the following order: ID, Name, Class. |
SendSlow (optional) |
The number of seconds to wait between characters before the next character is sent. |
Number of seconds If no value is provided, all of the text will be sent at one time. |
|
|
To click a button or other clickable elements, specify a line in the following format:
|
Or
|
Name |
Description |
Valid Values |
---|---|---|
Identifier (mandatory) |
The ID, name, class, text or xpath of the field. |
The entry cannot contain white spaces for ID, name, or class. |
Type |
The type of field in the HTML page |
ID/Name/Class/Text/XPath By default, fields are searched in the following order: ID, Name, Class. |
After a successful login, an element is required in order to verify that the correct page was loaded and the process was successful. To identify these elements, specify one of the following lines in the following format:
|
|
All validations must run at the end of the login process. |
Name |
Description |
Valid Values |
---|---|---|
Identifier (mandatory) |
The ID, name, class, text or xpath of the field. |
The entry cannot contain white spaces for ID, name, or class. |
Type |
The type of field in the HTML page |
ID/Name/Class/Text/XPath By default, fields are searched in the following order: ID, Name, Class. |
Execute a validation context compatible command after a validation block
Both of the validation parameters support the usage of the or
conditional operator for the following five validation-compatible commands:
-
Validation
-
iFrame
-
Error
-
Navigate
-
MainWindow
When a validation command occurs, the mechanism enters a validation context.
Each of the five validation-compatible commands listed above keep the validation context until a validation command successfully passes. This means:
-
When the validation passes successfully, the validation context compatible commands are cleared until a non-compatible validation context command occurs (any command that is different from the five commands listed above).
-
To execute a validation-compatible context command after a validation block, you must separate it from the validation block with a non-compatible validation context command.
If a validation command has not passed in a validation block sequence, a validation error occurs.
If a validation command does pass in a validation block sequence, the command execution continues.
The following Verify example shows how to perform a navigation action after validation is successful. This enables an end user to log on to their account , on a specific page.
In this example, the Wait command breaks the validation commands context. When the validation successfully passes, it clears the following validation commands up to the Wait command (not including the Wait command).
Verify example
username-element-id > {username} (searchby=id)
password-element-id > {password} (searchby=id)
submit-button-id > (Button) (searchby=id)
valid-validation-element-1-id > (Validation) (searchby=class)
(Wait=1)
(Navigate=https://next-page-url)
The Verify example below, which does not include the (Wait=1) command, is incorrect:
username-element-id > {username} (searchby=id)
password-element-id > {password} (searchby=id)
submit-button-id > (Button) (searchby=id)
valid-validation-element-1-id > (Validation) (searchby=class)
(Navigate=https://next-page-url)
If the required elements are enclosed in a frame, specify the following format to enter a frame where the identifier is known:
|
Name |
Description |
Valid Values |
---|---|---|
Identifier (mandatory) |
The ID, name, class, text or xpath of the field. |
The entry cannot contain white spaces for ID, name, or class. |
Type |
The type of field in the HTML page |
ID/Name/Class/Text/XPath By default, fields are searched in the following order: ID, Name, Class. |
-
Specify the following format to enter a frame that has no identifier:
(iFrame)
This format will also work in cases where an identifier is available, although its performance will be lower.
-
Specify the following format to return to the main window:
(MainWindow)
To navigate to a new URL, specify a line in the following format:
|
Name |
Description |
Valid Values |
---|---|---|
URL (mandatory) |
The URL to navigate to. |
Valid URL |
By default, when failing to login, the user will receive generic messages such as "Element not found". To provide more accurate error messages for the user such as "Invalid username or password", elements can be located on the page, and a relevant message can be attached to them.
To add this type of scenario, specify a line in the following format:
|
Name |
Description |
Valid Values |
---|---|---|
Identifier (mandatory) |
The ID, name, class, text or xpath of the field. |
The entry cannot contain white spaces for ID, name, or class. |
Type |
The type of field in the HTML page |
ID/Name/Class/Text/XPath By default, fields are searched in the following order: ID, Name, Class. |
Message |
The message that will be displayed to the user when this element is found. |
Text |
To generate a TOTP-based MFA code, specify a line in the following format:
|
Name |
Description |
Valid Values |
---|---|---|
Value(mandatory) |
The MFA device secret. The secret can be obtained when connecting the MFA device to the account. |
All characters are valid. |
|
To use the generated MFA code, enter the placeholder, &MFACode&, in the places that you want the MFA code to appear. |
WebFormFields example
In this example, the code will:
|
WebFormFields example for a site using iFrame
In this example, the username, password and button are all in an iFrame that has no identifier. |
|
CyberArk solutions as well as third-party products used by CyberArk solutions may contain digital signatures in files to ensure the files have not been altered and remain in their original state as shipped by CyberArk.
In order to ensure the integrity of the digital signatures, Certificate Revocation Lists (CRLs) published by the issuer of the signing certificates must be accessible to the system running the CyberArk solution. If access to the CRLs is prevented, this can result in a less secure environment since the signing certificate cannot be checked for revocation. It can also slow down the system as CyberArk or third-party products attempt to reach CRL distribution points that are unreachable, and the system has to wait for the timeout to complete its timeframe.
The conditional statements enable you to create blocks of webform field actions that will be executed based on the result of the conditional statement actions. You can form expressions ‘and’ ‘or’ conditional operators for different expression combinations. The language also supports nesting of conditional statements to create a complex control flow.
Each conditional statement must have both opening and closing commands to determine where the block of commands start and end.
Conditional statement opening and closing commands
The supported conditional statement opening and closing commands are described in the following table.
Opening command |
Closing command |
Usage |
---|---|---|
|
|
|
|
|
|
|
|
|
Conditional operators usage
You can use the following conditional operators between conditions:
-
and
-
or
Command restrictions
Each condition must be surrounded by parenthesis.
Each conditional operator must be after the closing parenthesis that surrounds the previous condition, and before the opening parenthesis of the subsequent condition.
The following examples show both the correct syntax to use as well as incorrect syntax.
if ( ( <condition> ) )
if ( ( <condition> ) and ( <condition> ) )
if ((( <condition> ) and ( <condition> ) ) or ( <condition> ) )
Example 1: This example shows invalid syntax using the conditional operator.
if ( ( <condition> ) ( <condition> ) )
if ((( <condition> ) and ( <condition> ) ) ( <condition> ) )
Example 2: This example shows invalid syntax using the parenthesis.
if ( ( <condition> and ( <condition> ) )
if ((( <condition> ) and <condition> ) ))
Example 3: This example shows invalid syntax using the underscore character (_).
if ( ( <condition> ) _ and ( <condition> ) )
if ((( <condition> ) and _ ( <condition> ) ))
Webform field conditional statement actions
Verifies whether an element exists or not.
Identifier > (Condition) (SearchBy=Type) (Exists ConditionalOperator ConditionValue)
Parameter |
Description |
---|---|
Identifier |
The ID, name, class, text, or xpath of the field. The entry cannot contain white spaces for ID, name, or class. Mandatory: Yes //*[@id="contentBody"]/div/div[2]/div[2]/h1 |
Type |
The type of field in the HTML page. By default, fields are searched in the following order: ID, name, class. Mandatory: No Valid values: ID, name, class, text, xpath |
ConditionalOperator |
The conditional operator used for result assessment. Mandatory: Yes Valid values: eq
|
ConditionValue |
Determines if the element will be present in the DOM or not. Mandatory: Yes Valid values: True/False |
Counts how many elements exist.
Identifier > (Condition) (SearchBy=Type) (Count ConditionalOperator ConditionValue)
Parameter |
Description |
---|---|
Identifier |
The ID, name, class, text, or xpath of the field. The entry cannot contain white spaces for ID, name, or class. Mandatory: Yes //*[@id="contentBody"]/div/div[2]/div[2]/h1 |
Type |
The type of field in the HTML page. By default, fields are searched in the following order: ID, name, class. Mandatory: No Valid values: ID, name, class, text, xpath |
ConditionalOperator |
The conditional operator used for result assessment. Mandatory: Yes Valid values: eq, ne, gt, ge, lt, le
|
ConditionValue |
Determines the number of elements in the DOM. The elements are counted and then compared to the calculation of the ConditionalOperator parameter value. Mandatory: Yes Valid values: Any positive numeric value |
This condition action is assessed on a comparison of replaceable values. It is not based on elements in the DOM.
Replaceable-placeholder > (Condition) (Placeholder ConditionalOperator ConditionValue)
Parameter |
Description |
---|---|
Replaceable-placeholder |
A placeholder for a replaceable parameter. Mandatory: Yes Valid values:
|
ConditionalOperator |
The conditional operator used for result assessment. Mandatory: Yes Valid values: eq
|
ConditionValue |
The expected value of the placeholder during runtime. Mandatory: Yes Valid values: Any string value |
if/else conditional statement example
%Identifier% > %Input Value% (SearchBy=Text\id\name\class)(sendslow=0.5)
if ((%Identifier% > (Condition) (SearchBy=Text\id\name\class) ( Exists [eq] %True\False% )) [and\or] ({myAccountParameter} > (Condition) ( Placeholder eq myAssumedAccountParameterValue )))
%Identifier% > %Input Value% (SearchBy=Text\id\name\class)
%Identifier% > (%Button\Click\Verification\Validation\Iframe%) (SearchBy=Text\id\name\class)
end-if
else-if ((%Identifier%> (Condition) (SearchBy=Text\id\name\class) ( Count [eq\ne\gt\ge\lt\le] %Numeric-value% )))
%Identifier% > %Input Value% (SearchBy=Text\id\name\class)
%Identifier% > (%Button\Click\Verification\Validation\Iframe%) (SearchBy=Text\id\name\class)
%Identifier% > (Validation)(SearchBy=Text\id\name\class)
end-else-if
else
%Identifier% > %Input Value% (SearchBy=Text\id\name\class)
%Identifier% > (%Button\Click\Verification\Validation\Iframe%) (SearchBy=Text\id\name\class)
end-else
%Identifier% > (Validation)(SearchBy=Text\id\name\class)
if/else conditional statement example explanation
Command |
Explanation |
---|---|
|
|
|
Determines the end of the current |
|
|
|
Determines the end of the current |
|
|
|
Determines the end of the current |
CPM Verify example
[Verify]
identifierLink > (Button) (searchby=id)
identifierId > {username} (searchby=id)
identifierNext > (Button) (searchby=id)
password > {password} (searchby=name)
if((conditionElementId1 > (Condition) (searchby=id)(exists eq true)))
nextPasswordBtn123 > (Button) (searchby=id)
end-if
else-if((conditionElementClass2 > (Condition) (searchby=class)(count gt 3)))
nextPasswordBtnXYZ > (Button) (searchby=id)
end-else-if
gb > (Validation) (searchby=class)
gbq1> (Validation) (searchby=class)
Step 3: Test the plugin
Before you integrate the plugin into a PAM - Self-Hosted environment for an end-to-end test, you can invoke the new plugin manually. This enables you to test the plugin more easily and quickly.
Before you begin testing the plugin, review the Prerequisites.
Create a user.ini file to simulate parameters
To simulate the parameters sent to the plugin by the CPM, create a user.ini file in the format described in the following sections.
The Credentials Management .NET SDK has a sample project that contains a sample user.ini file that you can use. |
The user.ini file contains multiple sections that define a set of account or platform properties. Specify the required parameters in each section.
The supported sections are:
Section | Description | Account Type |
---|---|---|
Target account properties | TargetAccount | |
[extrainfo] | Target account platform properties | TargetAccount.ExtraInfoProp |
[extrapass1] | Logon account properties | LogOnAccount |
[extrapass2] |
Extra account properties |
Extrapass2Account |
[extrapass3] | Reconcile account properties | ReconcileAccount |
[masterpass] | Master account properties (for dependency plugins). | MasterAccount |
-
Set the ManagementType policy parameter to password.
For the Target account, this can be done in the account or the platform properties. For other accounts, currently only passwords are supported.
-
Specify the following parameters in the Target account section, at the top of the user.ini file:
-
Current password: password
-
New password: newpassword
-
|
The log file created by the infrastructure will contain the following properties: safename, foldername, objectname and PolicyID. For this reason, they are all mandatory parameters when running the plugin manually. |
|
Parameters
Parameter |
Description |
Valid Values |
---|---|---|
ParameterFile |
The name of the parameter file. For more information see Create a user.ini file to simulate parameters. |
Full or relative path of an ini file. |
Action |
The activity to run. |
verifypass , changepass, or reconcilepass |