CyberArk Vault Integration

Control-M supports retrieval of secrets (such as passwords, access keys, or security keys) from CyberArk vaults.

Control-M communicates with the CyberArk vault via either of the following methods:

• CyberArk SDK Agent: A local CyberArk Software Development Kit (SDK) credential provider (CP) that is installed on an Agent, as shown in the following diagram:

  

• REST: A third-party CyberArk credential provider (CACP) that is stored in a third-party vault, as shown in the following diagram:

  

Setting Up a CyberArk Vault Integration

This procedure describes how to set up a CyberArk vault integration, which enables you to configure vault integration parameters and select the vault integrations that appear in Control-M SaaS.

Before You Begin

• Verify that you have installed and configured one of the following CyberArk components:

  • SDK Communication: CyberArk Credential Provider (CP) version 12.1 or higher on the Agent host machine

  • REST Communication: CyberArk Central Credential Provider (CCP) version 12.1 or higher

• For REST communication with CyberArk CCP through a proxy, ensure that proxy server settings are defined for the Agent, as described in Proxy Server Configuration, and that an agproxy.json file was generated by the Agent.

• For security reasons, BMC does not recommend that you use more than one application (identified by AppID) per Agent.

Begin

1. Open a command prompt window where your Agent is installed.

2. Run the Vault Configuration (vault-cfg) utility and configure Control-M integration with the vault, as follows:

   You can, alternatively, use the Vault CLI (vault-cli) utility, for backward compatibility with previous versions of Control-M.

   1. Navigate to the directory that contains the Vault Configuration utility:

      <AGENT_HOME>/ctm/cm/vault_cfg/

   2. Configure vault integration parameters by running one of the following commands:

      • Linux: ./vault-cfg.sh config update -p=<parameter> -v=<value>

      • Windows: vault-cfg.cmd config update -p=<parameter> -v=<value>

      Repeat this command for each parameter that you want to update. For descriptions of the available parameters, see CyberArk Vault Integration Parameters for SDK Communication or CyberArk Vault Integration Parameters for REST Communication.

      • If you want client certificate authentication when you use a REST connection, copy your private key into the same directory (<AGENT_HOME>/ctm/cm/vault_cfg/), and then configure the following parameters:

        • cyberark.<APPID>.client.certificate.password

        • cyberark.<APPID>.client.certificate.name

        • cyberark.<APPID>.client.certificate.type

      • After you configure the vault integration parameters, you can display the current parameter values by running one of the following commands:

        • Linux: ./vault-cfg.sh config display

        • Windows: vault-cfg.cmd config display

      • If you want to delete your settings and disable the vault integration, use one of the following commands:

        • Linux: ./vault-cfg.sh config delete

        • Windows: vault-cfg.cmd config delete

   3. If you want to use your own server certificate, create a keystore in this directory and import a server certificate for it, as described in Setting Up Your Own Server Certificate.

      After you create a keystore and import your server certificate, use the config update command (described in the previous step) to configure the truststore.name, truststore.password, and truststore.type parameters. Also set the cyberark.rest.disable.trustall parameter to true (instead of the default false).

   4. Test the connection to your vault by running one of the following commands:

      • Linux: ./vault-cfg.sh test -f=<secret_parameters_file>

      • Windows: vault-cfg.cmd test -f=<secret_parameters_file>

      Where

      <secret_parameters_file> is the path to a file that defines values for secret parameters in JSON format, as shown in the following example:

      Copy

      {
         "Type": "Secret:CyberArkVault:Basic",
         "AppID": "finance",
         "Safe": "financeDept",
         "Folder": "Root",
         "Account": "oracleSalaryService",
         "Reason": "I need it to export salaries for VP"
      }

      These parameters are described in CyberArk Secret Parameters in Connection Profiles. For a similar JSON format used by Control-M Automation API, see External Vault Secrets.

      For a list of possible return codes for the connection test, see CyberArk Vault Integration.

3. Select the vault integrations to use in centralized connection profiles or Run as User definitions, as described in Configuring System Settings.

   By default, all supported vault integrations are available when you want to retrieve secrets for password-type fields in connection profiles or Run as User definitions. Use this procedure to hide any integrations that are not relevant to you from appearing in the user interface.

   The selection of vault integrations does not affect the following:

   • Existing connection profile fields or Run as User fields that are already configured to retrieve secrets from vault integrations that are no longer enabled.

   • JSON references to secrets used by Control-M Automation API. For more information, see Secrets in Code.

Setting Up Your Own Server Certificate

This procedure describes how to set up your own server certificate, which involves creation of a keystore in the directory that contains the Vault Configuration utility and import of a server certificate for it.

Begin

1. Generate a new keystore in PKCS#12 format using the following command:

   keytool -genkeypair -alias <keystoreAlias> -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore /ctm/cm/vault_cfg/<your_keystore>.p12 -storepass <your_password>

2. Import a server certificate using the following command:

   keytool -importcert -trustcacerts -alias <serverCertAlias> -file /home/path/<your_server_certificate>.cer -keystore /ctm/cm/vault_cfg/<your_keystore>.p12 -storepass <server_certificate_password>

3. Import a root CA certificate using the following command:

   keytool -importcert -trustcacerts -alias <rootCAAlias> -file /home/path/<root_ca_certificate>.cer -keystore /ctm/cm/vault_cfg/<your_keystore>.p12 -storepass <root_ca_certificate_password>

CyberArk Vault Integration Parameters for SDK Communication

The following table lists the CyberArk Vault integration parameters that you can configure using the Vault CLI utility when you use SDK communication to connect with CyberArk CP.

CyberArk Vault Integration Parameters for REST Communication

The following table lists the CyberArk Vault integration parameters that you can configure using the Vault Configuration utility when you use REST communication to connect with CyberArk CCP.

CyberArk Secret Parameters in Connection Profiles

The following table describes the parameters that are used to locate and retrieve passwords or secrets from a CyberArk vault. These parameters appear when you select the Use External Vault option for any password-type field in the centralized connection profile parameters or Run as User parameters. You can choose between retrieval of the secret based on default CyberArk parameters or based on a query to CyberArk.

The following table describes parameters that are available for retrieval of a secret based on default CyberArk parameters.

The following table describes parameters that are available for retrieval of a secret based on a query to CyberArk.

property1=value1;property2=value2;property3=value3