Configure PreConnect custom code

This topic describes how to run custom logic before the login process. You can create a temporary user for the login process and implement an interface using a PreConnect DLL file provided by CyberArk. The implemented DLL can then be configured to be called prior to a connection, and the returned values can be used in the login process.

Implement the PreConnect DLL file

The CA DLL implements the IPreconnectContract interface by using CyberArk.PSM.WebAppDispatcher.PreconnectUtils.dll located in PSM.

Code and configuration sample

Let's implement a sample PreConnect CA DLL to understand the configuration.

using CyberArk.PSM.WebAppDispatcher.PreconnectUtils; //Reference the PreconnectUtils.dll provided with the WebAppDispatcher package using System; using System.Collections.Generic; using System.Security; using static CyberArk.PSM.WebAppDispatcher.PreconnectUtils.LogUtils; namespace CyberArk.PSM.WebAppDispatcher.RevertParametersPreconnect { //This preconnect example reverses all the parameters it receives public class ReverseParameters : IPreconnectContract { public Dictionary<string, SecureString> GetParameters(Dictionary<string, SecureString> parameters, WriteToLogHandler WriteToLogMethod) { //Write INFO message to dispatcher log WriteToLogMethod("Started Method", Consts.LOG_LEVEL_INFO); Dictionary<string, SecureString> newParameters = new Dictionary<string, SecureString>(); //Perform custom logic - Reverse every parameter received if (!(parameters == null || parameters.Count == 0)) { foreach (KeyValuePair<string, SecureString> entry in parameters) { //Name the returned parameter with suffix reversed_ //for example, if received parameter username will return parameter reversed_username newParameters[string.Format("reversed_{0}", entry.Key)] = Reverse(entry.Value); } } else { WriteToLogMethod("Parameters list is null or empty", Consts.LOG_LEVEL_INFO); } //Catch custom exception thrown from custom logic catch (MyException ex) { //Write ERRROR message to dispatcher log WriteToLogMethod(string.Format("my error was thrown. error: {0}", ex.ToString()), Consts.LOG_LEVEL_ERROR); //Always throw Preconnect Exception, otherwise a general error will be thrown from the WebAppDispatcher throw new PreconnectException(ex.Message); } //Catch all other types of exceptions thrown catch (Exception ex) { WriteToLogMethod(string.Format("general error was thrown. error: {0}", ex.ToString()), Consts.LOG_LEVEL_ERROR); //Always throw Preconnect Exception, otherwise a general error will be thrown from the WebAppDispatcher throw new PreconnectException(ex.Message); } WriteToLogMethod("Ended Method Successfully", Consts.LOG_LEVEL_INFO); //Successful run, return reversed parameters return newParameters; } private SecureString Reverse(SecureString secureStr) { //Reverse string logic } } }

(Optional) Reverse the username parameter

  1. Go to Administration > Configuration Options > Options > Connection Components > Target Settings > Client Specific and add the following parameters:

    • PreConnectDllName with value: CyberArk.PSM.WebAppDispatcher.RevertParametersPreconnect.dll

    • PreConnectParameters with value: username

  1. Do the following in the web form fields to use the reversed username:

Username > &reversed_username& (searchby=id)
Password > {Password}
Button_Enter > (Button) (searchby=class)
top-navbar__icon > (Validation) (searchby=id)

Create the PreConnect DLL

To be able to develop the logic that will be performed before running the connection, you need to implement the interface defined in the PreconnectUtils.dll file.

To create the PreConnect DLL:

  1. In the PSM\Components folder, locate the PreconnectUtils.dll file.

  2. Create the DLL by implementing the IPreconnectContract defined in the PreconnectUtils.dll file, and then implement the GetParameters method: GetParameters(Dictionary,string, SecureString> parameters, WriteToLogHandler WriteToLogMethod)

    Inputs

    Output

    Parameters - A key-value dictionary of the parameters retrieved from the account that are defined in the PreConnect parameter.

    WriteToLogMethod - A handle method used to write information to the logs. See To write information to the logs: below.

    A key-value dictionary of parameters used in the login process.
  3. Make sure that you put the PreConnect DLL in the PSM\Components folder.

To write information to the logs:

  • Use WriteToLogMethod to write to the logs.

  • Use Consts to define the log level.

     

    WriteToLogMethod("Start Method", Consts.LOG_LEVEL_INFO);

To return a custom error message to the end user:

  • Throw a PreconnectException exception with the error message that you want the end user to see.

     

    throw new PreonnectException("Preconnect exception");

    Any other exception that is thrown is written to the log only, and the end user will receive a general error message.

Configure the web application

To define the PreConnect DLL that will be used during the connection:

  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. Expand Target Settings, right-click Client Specific, and add the following two parameters.

    Parameter

    Description

    PreConnectDllName

    The name of DLL file that contains the Preconnect logic.

    Note: The DLL file must be located in the PSM Components folder.

    PreConnectParameters

    A comma-separated list of parameters that is sent to the PreConnect DLL file.

    Example: username,password

    Note: The parameter names are case-sensitive, so make sure to enter them using the same case as they are defined in the configuration options.

  4. If you want to use the values from the PreConnect DLL, add these values in WebFormFields, in the Input field. See Configure PreConnect custom code, above, in this topic. This is done for each connector.

     

    Different symbols are used for PreConnect parameters in WebFormFields.

    • Use the ampersand symbol & both at the start and end of the parameter name from the PreConnect DLL: &placeholder&
    • Use the brace symbol {} for account or configuration parameters: {placeholder}