Configuring the agent to work with CyberArk

Configure dynamic agents to work with CyberArk by creating a dedicated profile.

If you plan to use CyberArk as your password vault, configure the profile as follows:

[VaultProfile.Common]
Type = CyberArk
Description =
PasswordSolver = installation_dir/TWS/integrations/bin/libCyberArkVault.so
ConfigFile = TWA_DATA_DIR/integrations/config

Type

Specify the type of password vault to be used. This parameter is a string, and no validations are performed on its contents.

Description

Optionally write a description for the profile.

PasswordSolver

Contains the path to the password vault libraries. For example, you can point to the CyberArk libraries installed by default with the agent in the following paths:

On Windows operating systems: installation_dir\TWS\integrations\bin\CyberArkVault.dll
On UNIX operating systems: installation_dir/TWS/integrations/bin/libCyberArkVault.so

ConfigFile

Specify the name and full path of the configuration file for the password vault. If you have a CyberArk.ini configuration file from a previous installation, merge the contents of the file with the new configuration file. Alternatively, you can insert the whole configuration file directly in this parameter, for example by copying the whole CyberArk.ini file in this parameter.

For information about configuring secure communication with CyberArk, see Configuring secure communication with CyberArk.

After the agent is configured, you can proceed to define a job that is designed to securely retrieve passwords from the password vault, as described in Obtaining passwords from password vaults.

Defining parameters in the CyberArk.ini file

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/config_templ, as follows:

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
On UNIX operating systems, ensure you apply to the new file the same permissions and ownership settings assigned to the JobManager.ini file.
Fill in the parameters listed below as required.

You can also copy the updated file to a different path and specify the full path in the ConfigFile parameter of the profile you plan to use.

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 IBM® Workload Scheduler waits before sending a new password request to CyberArk.
RetryAttemptsForPasswordChangeInProcess: The number of times IBM Workload Scheduler 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 IBM Workload Scheduler 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 IBM Workload Scheduler waits for the host to answer the connection request.

Timeout

The time interval in seconds IBM Workload Scheduler 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, IBM Workload Scheduler 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, IBM Workload Scheduler 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, IBM Workload Scheduler 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:

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.

you generate new certificates using certman

Generate the certificates using certman, as described in Managing certificates using Certman
Set the SSL cert type parameter to pem, which is the format used by certman.
Specify in the SSL certificate parameter the full path to the tls.crt file generated by the certman command.
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.

After the agent is configured, you can proceed to define a job that is designed to securely retrieve passwords from the password vault, as described in Obtaining passwords from password vaults.

Configuring secure communication with CyberArk

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:

Provide CyberArk with your CA, which validates your certificate.
CyberArk returns its CA, which validates the certificate from CyberArk.
Depending on whether you use certificates in pem or p12 format, specify the following parameters:
certificates 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.

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

CyberArk provides you with private key and certificate.
Depending on whether you use certificates in pem or p12 format, specify the following parameters:
certificates in pem format

Specify the full path to the key in the SSLKey and the full path to the certificate in the SSLCertificate parameters.

certificates 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.
Import the CyberArk CA into the pem truststore which must be specified in the SSLCACertificate parameter in the CyberArk.ini file.