Configuring the agent to work with CyberArk

Configure dynamic agents to work with CyberArk by configuring the CyberArk.ini file.

About this task

Set up the CyberArk.ini file to configure password retrieval.
To configure CyberArk, you can use the CyberArk.ini template file available in TWS/integrations/bin, as follows:
  1. Create a copy of the template file to one of the following paths, depending on your operating system:
    On Windows operating systems
    installation_directory\integrations\config
    On UNIX operating systems
    TWA_DATA_DIR/integrations/config
  2. On UNIX operating systems, ensure you apply to the new file the same permissions and ownership settings assigned to the JobManager.ini file.
  3. Fill in the parameters listed below as required.

In the CyberArk.ini file, the following sections and parameters are available:

[CyberArk.Config]
CPAccessLibrary
The full path to the CyberArk proprietary library file.
HandlePasswordChangeInProcess
The operation to be performed if another user changes the password while you are requesting it from CyberArk. Supported values are true and false.

If you set this property to true, the job remains in waiting status and password retrieval is attempted again, based on the values set for the RetryIntervalForPasswordChangeInProcess and RetryAttemptsForPasswordChangeInProcess parameters.

RetryIntervalForPasswordChangeInProcess
The time interval in seconds HCL Workload Automation waits before sending a new password request to CyberArk.
RetryAttemptsForPasswordChangeInProcess
The number of times HCL Workload Automation retries to obtain the password from CyberArk. If the specified number of retries is exceeded, the operation fails.

[CyberArk.CP.Connection]

This section applies only when you use the Credential Provider (CP) and specify the full path to the CyberArk library file in the CPAccessLibrary property.
Port
The port that is used to connect to the CP.
ConnectionTimeout
The time interval in seconds HCL Workload Automation waits for the host to answer the connection request.

[CyberArk.CCP.Connection]

This section applies only when you use the Central Credential Provider (CCP) and is used when you leave the CPAccessLibrary property empty. These properties are mandatory.
Host
The host name of the workstation where CyberArk Central Credential Provider is installed.
Protocol
The protocol used to connect to the host.
Port
The port used to connect to the host.
Path
The path where the REST API is located.
ConnectionTimeout
The time interval in seconds HCL Workload Automation waits for the host to answer the connection request.
Timeout
The time interval in seconds HCL Workload Automation waits for CyberArk to return the password.
FollowLocation
Set this property to true to enable the HTTP protocol. You cannot enable the HTTP protocol from the command line. This property instructs the composer command to follow any Location: header that the server sends as part of the HTTP header in a 3xx response. The Location: header can specify a relative or an absolute URL to follow.
SSLVerifyServer
Specify yes if server authentication is to be used in SSL communications.
Proxy
The name of the proxy server used when connecting to the specified host.
ProxyPort
The TCP/IP port number of the proxy server used when connecting to the specified host.
SSLVersion
Specify the SSL version to be used. Supported values are:
  • atleast.TLSv1.0
  • atleast.TLSv1.1
  • atleast.TLSv1.2
  • atleast.TLSv1.3
where you specify the minimum version of the TLS protocol to be used. In this case, HCL Workload Automation uses the specified version of the protocol or a higher version, if supported.
  • max.TLSv1.0
  • max.TLSv1.1
  • max.TLSv1.2
  • max.TLSv1.3
where you specify the maximum version of the TLS protocol to be used. In this case, HCL Workload Automation uses the specified version of the protocol or a lower version.
  • TLSv1.0
  • TLSv1.1
  • TLSv1.2
  • TLSv1.3
where you specify the exact version of the TLS protocol to be used. In this case, HCL Workload Automation uses the specified version of the protocol.
SSLCiphers
Define the ciphers that the workstation supports during an SSL connection.
If you want to use an OpenSSL cipher class, use the following command to find out the list of available classes: 
openssl ciphers

For a full list of supported ciphers, see SSL Ciphers and OpenSSL.

SSLCipherSuites
Specify one or more supported algorithms for TLS version 1.3, This option does not apply to TLS version 1.2 or earlier.
SSLConfigFile
Specify the name and path of the OpenSSL configuration file. See OpenSSL documentation for details about the file format and options. If you modify this file, ensure the changes are consistent with the security configuration in your environment.

[CyberArk.CCP.Connection.OpenSSL]

For more information about configuring secure communication with CyberArk, see Configuring secure communication with CyberArk.
SSLKey
The full path to the private key file in pem format.
If you use certificates in pem format
Specify the full path to the private key file in pem format. For example, if you use certman to generate the certificates, specify in this parameter the full path to the tls.key file.
If you use certificates in p12 format
Leave this parameter blank.
SSLKeyPwd
The full path to the file containing the password encoded in Base64 for the private key.
SSLCertificate
Specify the full path to the local certificate file used in SSL communication. You can either use the certificates available on the agent or generate brand new certificates using the certman command, as follows:
If you use the certificates available on the agent
Specify in the SSL certificate parameter the full path to the certificates, for example /<TWS_DATA_DIR>/ssl/certs/TWSClientKeyStore.p12. This ensures secure communication without further steps.
If you generate new certificates using certman
  1. Generate the certificates using certman, as described in Managing certificates using Certman
  2. Set the SSL cert type parameter to pem, which is the format used by certman.
  3. Specify in the SSL certificate parameter the full path to the tls.crt file generated by the certman command.
  4. Specify in the SSLKey parameter the full path to the private key file.
SSLCertificateType
Specify the type of your private key and certificate file used in SSL communication. Supported formats are p12 and pem .
If the certificate type is in pem format
  • Specify the full path to the private key file in the SSLKey parameter.
  • Specify the full path to the local certificate file in the SSLCertificate parameter.
If the certificate type is in p12 format
  • Store both private key and certificate in the p12.
  • Leave the SSLKey parameter blank.
  • Specify the full path to the local certificate file in the SSLCertificate parameter.
SSLCACertificate
Specify the name of the file containing the trusted certification authority (CA) certificates required for SSL authentication. The CAs in this file are also used to build the list of acceptable client CAs passed to the client when the server side of the connection requests a client certificate. This file is the concatenation, in order of preference, of the various PEM-encoded CA certificate files.
SSLRandomSeed
Specify the pseudo random number file used by OpenSSL on some operating systems. Without this file, SSL authentication might not work correctly.
[CyberArk.AppDescs]
AppID
The unique ID of the application issuing the password request. This parameter is required.
[CyberArk.Query]
Safe
The name of the Safe where the password is stored.
Folder
The name of the folder where the password is stored.
Object
The name of the password object to retrieve.
Username
Defines search criteria according to the UserName account property.
Address
Defines search criteria according to the Address account property.
PolicyID
Defines the format that will be used in the setPolicyID method.
Database
Defines search criteria according to the Database account property.
[CyberArk.Query.Result]
NormalizedUsername
Standardized format of a user name.

What to do next

After the agent is configured, you can proceed to define a job that is designed to securely retrieve passwords from CyberArk.

Configuring secure communication with CyberArk

About this task

To establish secure communication, you can use several certificate formats. The required configuration varies depending on the format you use, as follows:
If the certificate type is in pem format
  • Specify the full path to the private key file in the SSLKey parameter.
  • Specify the full path to the local certificate file in the SSLCertificate parameter.
If the certificate type is in p12 format
  • Store both private key and certificate in the p12.
  • Leave the SSLKey parameter blank.
  • Specify the full path to the local certificate file in the SSLCertificate parameter.
When establishing secure communication with CyberArk, you can encounter one of the following scenarios:
You want to use your own certificates and CA
The following steps apply:
  1. Provide CyberArk with your CA, which validates your certificate.
  2. CyberArk returns its CA, which validates the certificate from CyberArk.
  3. Depending on whether you use certificates in pem or p12 format, specify the following parameters:
    If certificates are in pem format
    Specify the full path to the private key file in the SSLKey and the full path to the local certificate in the SSLCertificate parameters.
    If certificates are in p12 format
    1. Add private key and certificate into a p12 keystore.
    2. Specify the full path to the p12 keystore you just created in the SSLCertificate parameter.
    3. Leave the SSLKey parameter blank.
  4. Import the CyberArk CA into the pem truststore which must be specified in the SSLCACertificate parameter in the CyberArk.ini file.
You request the certificates from CyberArk
The following steps apply:
  1. CyberArk provides you with private key and certificate.
  2. Depending on whether you use certificates in pem or p12 format, specify the following parameters:
    If certificates are in pem format
    Specify the full path to the key in the SSLKey and the full path to the certificate in the SSLCertificate parameters.
    If certificates are in p12 format
    1. Add private key and certificate into a p12 keystore.
    2. Specify the full path to the p12 keystore you just created in the SSLCertificate parameter.
    3. Leave the SSLKey parameter blank.
  3. Import the CyberArk CA into the pem truststore which must be specified in the SSLCACertificate parameter in the CyberArk.ini file.