Web applications for PSM
This topic describes how to create PSM connection components for web applications.
Prerequisites
-
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.
-
Microsoft Edge requires further hardening configuration. For details, see PSM Hardening Tasks.
-
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.
-
Latest version of Secure Web Application Connectors Framework, download from CyberArk Marketplace > Integrations > Secure Web Application Connectors Framework.
Supported browsers
CyberArk may choose not to provide maintenance and support services for Web applications for PSM 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. |
You can configure PSM connection components for web applications based on a default generic connection component that is created in the PVWA automatically during installation.
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 Microsoft Edge is supported; however, IE mode is not supported. |
Click here to download this version |
To prevent incompatibility issues with the PSM 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 machine 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 PSM Components folder.
Configuration
You can configure connection components for web applications based on a default generic connection component that is created in the PVWA automatically during installation.
-
Extract the Secure Web Application Connectors Framework zip file that you downloaded to any location on the PSM server.
-
Copy all the files from the Components folder in the zip file to the PSM Components folder on your PSM machine.
-
In the System Configuration page, in the Component Settings, click Options, and expand Connection Components.
The defined connection components appear.
-
Right-click PSM-WebAppSample, and select Copy.
For versions 10.1 or lower, copy PSM-WebFormSample.
-
Right-click Connection Components, and select Paste Connection Component.
A new connection component is added to the bottom of the list. This connection component is also called PSM-WebAppSample.
-
Change the Id and DisplayName of the new connection component.
For versions 10.1 or lower, under Target Settings, set ClientDispatcher to "{PSMComponentsFolder}\CyberArk.PSM.WebAppDispatcher.exe" "{PSMComponentsFolder}".
If you are using LogonAccount, do the following steps:
-
Go to Target Settings > Supported Capabilities, and click Add Capability.
-
Define the following setting:
Id: LogonAccount
-
Go to Target Settings > Web Form Settings.
-
Define the following properties:
Property
Description
LogonURL
The address of the web application.
Specify the URL of the login page.
The URL can include dynamic parameters such as the address that is replaced with the value of the corresponding property of the account.
https://accounts.google.com/ServiceLogin
https://{Address}
http://{Address}/Welcome/Login
Describes the list of login actions. For details, see Webform fields EnforceCertificate
ValidationWhether or not PSM will validate target website certificates when initiating PSM connections. This enables PSM to connect to local websites that do not have valid certificates, such as LAN applications with self-signed certificates.
To connect to local websites that use self-signed certificates, select No.
-
In Edit target > Client specific settings, define the following:
Name Description ActionTimeout
The maximum number of seconds to wait for an action to complete.
Valid values: Positive number
Default value: 10
PageLoadTimeout
The maximum number of seconds to wait for a page to load.
Valid values: Positive number
Default value: 30
BrowserPath
Path to the browser exe file
Valid values: Full path
DriverFolder
Folder the drive is located.
Valid values: Folder path
-
In Target Settings, under the ClientApp properties, set the browser.
Valid values
Default value
Chrome, Edge
Chrome
-
Under Lock Application Window, ensure that the MainWindowClass property is set to Chrome_WidgetWin_1, which is the correct value for all supported browsers.
- Click OK to save the new Connection Component configurations and return to the System Configuration page.
-
Click Platform Management to display a list of supported target account platforms.
-
Select the platform to configure, and then click Edit.
The settings page for the selected platform appears.
-
Expand UI & Workflows, right-click Connection Components, and then select Add Connection Component.
A new connection component is added to the current list of connection components that are configured for this platform.
-
In the new Connection Component, define the following properties:
Name
Description
ID
The unique ID that identifies the connection component that you created previously for the specific command.
Enable
Whether or not this connection component will be enabled for this platform. Select Yes.
-
Do one of the following actions:
- Click Apply to apply the new platform configurations.
- Click OK to save the new platform configurations and return to the System Configuration page.
When creating or linking a connection component, add a ">" (right angle bracket) to the ForbiddenCharacters parameter of the platform. |
Convert WebForm to WebApp
You can convert any connector that is based on the WebFormDispatcher.
To convert the connector from WebForm to WebApp:
- In the PVWA, click Administration > Configuration Options, and then click Options.
- In the left pane, expand Connection Components, and then expand the relevant connector.
-
Click Target Settings, and then do the following:
Property
Value
ClientDispatcher
Change the value to: "{PSMComponentsFolder}\CyberArk.PSM.WebAppDispatcher.exe" "{PSMComponentsFolder}"
ClientApp
Change the value to the relevant browser. For details, see Select the browser.
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. For xpath, when using brackets [ ], include a caret (^) before each bracket. Example: //*[@id="contentBody"]/div/div[2]/div[2]/h1 //*^[@id="contentBody"^]/div/div^[2^]/div^[2^]/h1 |
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. For xpath, when using brackets [ ], include a caret (^) before each bracket. Example: //*^[@id="contentBody"^]/div/div^[2^]/div^[2^]/h1 |
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. For xpath, when using brackets [ ], include a caret (^) before each bracket. Example: //*^[@id="contentBody"^]/div/div^[2^]/div^[2^]/h1 |
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. For xpath, when using brackets [ ], include a caret (^) before each bracket. Example: //*^[@id="contentBody"^]/div/div^[2^]/div^[2^]/h1 |
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 For xpath, when using brackets [ ], include a caret (^) before each bracket. Example: //*^[@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 For xpath, when using brackets [ ], include a caret (^) before each bracket. Example: //*^[@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 |
PSM example
identifierId > {username}
identifierNext > (Button)
password > {password}
passwordNext > (Button)
if((conditionElementId1 > (Condition) (searchby=id)(exists eq true)))
signExistingUserOutElementId > (Button) (searchby=id)
end-if
else
nextPasswordBtnXYZ > (Button) (searchby=id)
end-else
gb > (Validation)
gbq1 > (Validation)