Skip to Content

Configuring the CyberArk adapter

You configure an adapter in TrueSight Orchestration Grid Manager. The configuration provides information about how the adapter interacts with the CyberArk application. Although each adapter must have a unique name, you can create multiple adapters with the same adapter type to allow for different configuration properties. 

You configure an adapter using a form view or an XML view. You can switch to the XML view to configure elements and attributes that are not available as fields on the form view. After you switch to the XML view and save the adapter configuration, you cannot use the form view for editing it later.

To configure the actor adapter

  1. On Grid Manager, go to Manage > Adapters.
  2. From the Adapters in Repository list, select the ro-adapter-cyberark adapter, and click Add to Grid to add it in the Adapters on Grid list.
  3. Click Configure.
  4. Enter a unique name and an optional description. 
    The default name of the adapter is CyberArkActorAdapter.

The following table describes the configuration elements for the actor adapter.

UI label

XML element

Description

Required

WebSDK Endpoint Url

<websdk-endpoint-url>

Specifies the CyberArk server endpoint URL to invoke the WebSDK APIs.

Valid format: <HTTP_PROTOCOL>://<CyberArkWebSDKEndPointHost>:<port>

Examples: 

https://cyberArk.websdk.endpoint:443

https://cyberArk.websdk.endpoint:8080

Warning

Note

Do not provide any forward slash after the host or port.

No

AIM Endpoint Url

<aim-endpoint-url>

Specifies the CyberArk Application Identity Manager (AIM) service endpoint URL to retrieve credentials using AppID and query.

Valid format: <HTTP_PROTOCOL>://<CyberArkAIMEndopintHost>:<port>

Examples: 

https://cyberArk.aim.endpoint:9876

http://cyberArk.aim.endpoint:8081

Warning

Note

Do not provide any forward slash after the host or port.

Yes

Request Timeout

<request-timeout>

Specifies the time, in seconds, to wait when establishing a connection.

No

Private Key File

<private-key-file>

Specifies the file containing the private key that is used to sign the HTTP request to invoke the AIM API to retrieve the credentials.

Supported format is Privacy Enhanced Mail (PEM).

Success

Recommendation

BMC recommends that you configure the APP ID with client certificate authentication to restrict access to the Application IDs using addresses and certificate serial numbers to be able to access using client certificate authentication.

Conditional; required if you do not want to specify in the adapter request.

Required if you specify the <certificate-file> element.

Certificate File

<certificate-file>

Specifies the file containing the public key (X509 Certificate) that is used to sign the HTTP request to invoke the AIM API to retrieve the credentials.

Success

Recommendation

BMC recommends that you configure the APP ID with client certificate authentication to restrict access to the Application IDs using addresses and certificate serial numbers to be able to access using client certificate authentication.

Conditional; required if you do not want to specify in the adapter request.

Required if you specify the <private-key-file> element.

Character Set

<character-set>

Specifies the supporting CharSet.

Default value: UTF-8

No

Allow Unsigned Certificate

<allow-unsigned-certificate>

Specifies whether to allow unsigned certificates from trusted zones.

This applies to the Web SDK endpoint URL and AIM endpoint URLs specified in the adapter configuration only for the HTTPS protocol.

Valid values: true (default), false

No

KeyStore File

<keystore-file>

Specifies the path to the Java KeyStore file (JKS) that contains the client certificate and private key to invoke the AIM API to retrieve the credentials.

BMC recommends that you use the <keystore-file> to ensure that your certificates and private key are password protected.

Warning

Notes

  • The KeyStore file must contain the certificates and the private key.
  • If you specify the <keystore-file> element, then the <private-key-file> and <certificate-file> elements are ignored.
  • The KeyStore type must be Java KeyStore. This is required by the adapter to use the KeyStore for digital signature, and to sign the request to authenticate.

To convert your certificate and private key provided by the CyberArk administrator in a source KeyStore to Java KeyStore, do these:

  1. (For a PEM format): Run the following command to first convert it to a PKCS #12 file and then run the command to convert it to Java KeyStore:

    openssl pkcs12 -export -in [path to certificate] -inkey [path to private key] -certfile [path to certificate ] -out testkeystore.p12

  2. (For a PKCS #12 format) Run the following command:

    keytool -importkeystore -srckeystore <path_to_sourceCyberArkPKCS12Client.p12> -srcstoretype pkcs12 -<path_to_destkeystore destCyberarkJKSClient.jks> -deststoretype JKS

For more information about creating Java KeyStore file from existing private key and certificate file, see http://xacmlinfo.org/2014/06/13/how-to-keystore-creating-jks-file-from-existing-private-key-and-certificate/.

No

KeyStore Password

<keystore-password>

Specifies the password to the Java KeyStore.

Conditional;
required if you specify the KeyStore file.

Key Password

<key-password>

Specifies the password of the key contained in the Java KeyStore.

Warning

Note

If you do not specify the key password, then the value of the <keystore-password> is used as the key password.

No

The following figures describe the XML sample for the actor adapter configuration:

XML sample for configuring the CyberArk adapter with private key and certificate file.

<config>
  <websdk-endpoint-url>http://services-uscentral.skytap.com:13691</websdk-endpoint-url>
  <aim-endpoint-url>https://services-uscentral.skytap.com:13703</aim-endpoint-url>
  <private-key-file>C:\CyberArk\CyberArkPrivateKey.pem</private-key-file>
  <certificate-file>C:\CyberArk\CyberArkClientcert.crt</certificate-file>
  <allow-unsigned-certificate>false</allow-unsigned-certificate>
</config> 

XML sample for configuring the CyberArk adapter with KeyStore file (JKS format) and password.

<config>
   <websdk-endpoint-url>http://services-uscentral.skytap.com:13691</websdk-endpoint-url>
   <aim-endpoint-url>https://services-uscentral.skytap.com:13703</aim-endpoint-url>
   <private-key-file></private-key-file>
   <certificate-file></certificate-file>
   <keystore-file>C:\CyberArk\CyberArkClientKeystore.jks</keystore-file>
   <keystore-password>jkspassword</keystore-password>
   <key-password>CyberarkPassword</key-password>
   <allow-unsigned-certificate>true</allow-unsigned-certificate>
</config>

Enabling custom logging

To enable custom logging for the adapter, you must specify a log file name. You can also provide additional parameters for logging.

Warning

Note

You must be using

WarningSome content is unavailable due to permissions.

version 7.8 or later to use the custom logging feature. These parameters will be ignored in earlier versions of

WarningSome content is unavailable due to permissions.

Platform.

These parameters are available with supported adapter versions. See

WarningSome content is unavailable due to permissions.

Content documentation for details.

  • Log File Name: Provide a name for the log file.
    This file will be stored in the AO_HOME/tomcat/logs directory. If Log File Max Backup Index value is greater than 0, the log file name is suffixed with the backup index. For example, if the parameter value is a.log, backup log files will have names, such as a.log.1, a.log.2.
  • Log File Size: Specify a size limit for the log file. 
    If the value specified for Log File Max Backup Index is greater than 0, when the specified size is reached, the current file is renamed with the suffix .1. Otherwise, the log file will be reset and over-written. The default value is 10MB. The available units are KiloBytes (KB), MegaBytes (MB) or GigaBytes (GB).
  • Log File Max Backup Index: Enter the maximum number of backup files allowed. The default value is 10.
  • Log File Append: Select this option to append new log information to the existing information in the file. If unselected, the file will be overwritten with new log information.

  • Log Level: Enter the logging level using one of the following choices:

    Logging level

    Description

    DEBUG

    The most detailed logging level; logs low-level messages, normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions

    INFO

    (default)

    Logs normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions

    WARN

    Logs recoverable erroneous conditions and unrecoverable erroneous conditions

    ERROR

    The least detailed logging level; logs only error conditions that are not usually recoverable

Encrypting an element's contents

You can add the attribute secure="true" to an XML adapter element XML view to ensure that the element's contents is encrypted when displayed.

Warning

Note

You must be using

WarningSome content is unavailable due to permissions.

Platform version 7.8 or later to use this encryption attribute.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

TrueSight Orchestration Content 21.3