Web applications for PSM

This topic describes how to create PSM connection components for web applications.

Prerequisites

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.

  1. Extract the Secure Web Application Connectors Framework zip file that you downloaded to any location on the PSM server.

  2. Copy all the files from the Components folder in the zip file to the PSM Components folder on your PSM machine.

  1. In the System Configuration page, in the Component Settings, click Options, and expand Connection Components.

    The defined connection components appear.

  2. Right-click PSM-WebAppSample, and select Copy.

     

    For versions 10.1 or lower, copy PSM-WebFormSample.

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

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

  1. Go to Target Settings > Supported Capabilities, and click Add Capability.

  2. Define the following setting:

    Id: LogonAccount

  1. Go to Target Settings > Web Form Settings.

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

    WebFormFields

     

    		 Describes the list of login actions. For details, see Webform fields

    EnforceCertificate
    Validation

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

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

  1. In Target Settings, under the ClientApp properties, set the browser.

    Valid values

    Default value

    Chrome, Edge

    Chrome

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

  1. Click Platform Management to display a list of supported target account platforms.

  2. Select the platform to configure, and then click Edit.

    The settings page for the selected platform appears.

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

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

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

  1. In the PVWA, click Administration > Configuration Options, and then click Options.
  2. In the left pane, expand Connection Components, and then expand the relevant connector.

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

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

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.

 

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

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:

  
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.

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:

  
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.

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:

  
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.

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

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

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

  • 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

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

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

  • &myPreconnectParameter&

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

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)

Configure PreConnect custom code