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:

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.

  1. Download the latest Web Application CPM Plugin Framework from the Marketplace.

  2. 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.

  3. Import the platform:

    1. In the PVWA, go to Administration > Platform Management, and click Import Platform.

    2. Select the Plugin.WebApp.Import.Platform-vXX.X.X.X-Master.zip file that you downloaded.

  4. Duplicate the Generic Web App platform, and change its name to the new platform.

  5. Edit the WebForm settings

    1. 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.

  6. 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.

  7. 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.

  8. 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:

    1. Enter Import-Module .\CreateUserProfile.ps1

    2. 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 Micsrosoft 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.

  1. Create a new local user.

  2. 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

  3. 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:

  
Identifier > Value (SearchBy=Type) (SendSlow=Time)


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.

 

  • For parameters from the reconcile account, start with "reconcileaccount\". For example: {reconcileaccount\password}

  • For logon account parameters, start with "logonaccount\". For example: {logonaccount\password}

  • For extrapass2 account parameters, start with "extraaccount\". For example: {extraaccount\password}

  • For master account parameters, start with "masteraccount\". For example: {masteraccount\newpassword}

To click a button or other clickable elements, specify a line in the following format:

  
Identifier > (Button) (SearchBy=Type)

Or

  
Identifier > (Click) (SearchBy=Type)

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:

  
Identifier > (Validation) (SearchBy=Type)
  
Identifier > (Verification) (SearchBy=Type)
 

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:

  
Identifier > (iFrame) (SearchBy=Type)


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:

  
(Navigate=URL)


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:

  
Identifier > (Failure) (SearchBy=Type)(Message=Message)


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:

  
Run Generate_TOTP_MFA_Code (MFADeviceSecret=value)

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

  1. Go to the GMail login page

  2. Inspect the HTML code of the "Email or phone" field:

    As you can see, the ID of the field is "identifierId". We will specify its value as the username. Thus, the first line is:

    
identifierId > {username}

  1. Subsequent values as follows:

    identifierId > {username}
identifierNext > (Button)
password > {password}
passwordNext > (Button)
gb > (Validation)
gbq1 > (Validation)

In this example, the code will:

  1. Enter the username to the "Email or phone" field.
  2. Press the "Next" button.
  3. Enter the password to the "Enter your password" field.
  4. Press the "next" button.
  5. Validate that either "gb" or " gbq1" (the icon fields at the top right) are available.
 

WebFormFields example for a site using iFrame

gsft_main> (iframe)
user_name>{Username}
user_password>{Password}
sysverb_login>(Button)
 (mainwindow)
nav-settings-button>(Validation)(searchby=id)
application_picker_select>(Validation)(searchby=id)

In this example, the username, password and button are all in an iFrame that has no identifier.
  
user_name>{Username}
user_password>{Password}
sysverb_login>(Button)
Run Generate_TOTP_MFA_Code (MFADeviceSecret=ZR47PH6OKPRAQRJLQ3KWNL37IP4RWI4NWQIV7BSXEJ63OAPVCWYAQL6AZDLAI55R)
mfa_device_code_enter > &MFACode& (searchby=class)
nav-settings-button>(Validation)(searchby=id)
application_picker_select>(Validation)(searchby=id)
{{}}

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

if ()

end-if

  • Each series of command blocks must begin with an if conditional statement.

  • Each if command determines the beginning of a new series of command blocks.

else-if ()

end-else-if

  • This conditional statement is optional in a series of command blocks.

  • Use the else-if command only in the following scenarios:

    • After an end-if command

    • After an end-else-if command (after a previous else-if command block)

  • Each series of block statements can contain one or more consecutive else-if command blocks.

  • You cannot use else-if after an else command.

else

end-else

  • Use the else command only in the following scenarios:

    • After an end-if command

    • After an end-else-if command (after a previous else-if command block)

  • Use only one else command in a series.

  • The else command does not require any conditions. It will always return a positive result.

  • The else command determines the end of a series of block commands.

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

  • eq = equals

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

  • eq = equals

  • ne = not equals

  • gt = greater than

  • ge = greater than or equals

  • lt = less than

  • le - less than or equals

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:

  • &MFACode&

  • {myAccountParameter}

ConditionalOperator

The conditional operator used for result assessment.

Mandatory: Yes

Valid values: eq

  • eq = equals

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

 
if (
(%Identifier% > (Condition) (SearchBy=Text\id\name\class) ( Exists [eq] %True\False% )) [and\or]({myAccountParameter} > (Condition) ( Placeholder eq myAssumedAccountParameterValue )))

  • Conditions: Searches for elements by the given SearchBy option, looking for %Identifier%.

    • Exists: Checks if the element corresponds to the given Boolean value.

  • Conditional operators:

    • And: All conditions must be true for the condition to be positive.

    • Or: One of the conditions must be true for the condition to be positive.

  • If the conditional statement is positive, the current command block is executed and all the following command blocks will be filtered and not executed.

  • If the entire condition is negative, the current command block will be filtered and not executed.

 
end-if

Determines the end of the current if command block.

 
else-if ((%Identifier%> (Condition) (SearchBy=Text\id\name\class) ( Count [eq\ne\gt\ge\lt\le] %Numeric-value% )))

  • Condition: Searches for elements by the given SearchBy option, looking for %Identifier%.

  • Checks if the number of elements corresponds to the numeric value of the given conditional operator.

  • If the conditional statement is positive, the current command block is executed and all the following command blocks will be filtered and not executed.

  • If the entire condition is negative, the current command block will be filtered and not executed.

 
end-else-if

Determines the end of the current else-if command block.

 
else

  • This condition always returns a positive result.

  • If this conditional statement is reached, and it was not filtered by previous commands, the command block will always be executed.

 
end-else

Determines the end of the current else command block.

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

  1. 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.

  2. Specify the following parameters in the Target account section, at the top of the user.ini file:

    • Current password: password

    • New password: newpassword

  
[targetaccount]
username=<Target Account Username>
newpassword=<Target Account New Password>
password=<Target Account Password>
safename=Safename
foldername=Foldername
objectname=Objectname
PolicyID=PlatromPolicyID
[extrapass1]
username=<Logon Account Username>
password=<Logon Account Password>
[extrapass3]
username=<Reconcile Account Username>
password=<Reconcile Account Password>
[extrainfo]
VerifyURL=https://test
ChangeURL=https://test
ReconcileURL=https://test
WebFormFieldsFile=ElementsData.ini
RunVerifyAfterChange=No
RunVerifyAfterReconcile=No
ActionTimout=10
PageLoadTimeout=30
EnforceCertificate=Yes
 

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.
  
bin\CANetPluginInvoker.exe <ParameterFile> <Action> CyberArk.Extensions.Plugin.WebApp.dll True

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