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.

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

Configuration

You can configure platforms for Web applications based on a default 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 Web Form 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 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:

Test the plugin

Before integrating the plugin into a PAM - Self-Hosted environment for an end-to-end test, you can invoke the new plugin manually for faster and easier testing.

Before you begin testing, review the Prerequisites.

Parameter File

To simulate the parameters given to the plugin by CPM, create a user.ini file in the format described below.

 

A sample user.ini file is provided with the sample project provided with Credentials Management .NET SDK

Sections

The parameters user.ini file is built out of sections, each defining a set of account or platform properties.

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

In each section, specify the required parameters.

Secrets

To run the plugin with passwords

  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 at the Target account section (top of the ini file):

    ■ Current password: password
    ■ New password: newpassword

Example

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

To run the plugin, use the following command:

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

 Full or relative path of an ini file.
Action The activity to run.

verifypass , changepass, or reconcilepass

Web Form Fields

Specify the information listed below in WebFormFields. 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 identity these elements, specify a line in the following format:

  
Identifier > (Validation) (SearchBy=Type)

Or

  
Identifier > (Verification) (SearchBy=Type)

 

 
  • All validations must run at the end of the login process.
  • The relation between validations will be "or". If one of the fields defined in the validations will be find, the login will be considered a success.

 

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.

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.

Value should be in Base32 or hex string format.

 

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)
{{}}