CyberArk Vault Integration

You can integrate Control-M with a CyberArk vault where you store and manage sensitive information (called secrets), such as passwords, access keys, or security keys. This integration enables Agents to retrieve secrets from your vault only when they connect to your plug-in application servers and run jobs, so that sensitive information is not saved in Control-M components. Communication with the CyberArk vault can be either SDK communication through a local Credential provider (CP) installed on the Agent host machine or REST communication through a central Credential Provider (CCP).

The following diagram demonstrates how Control-M SaaS retrieves secrets from a CyberArk vault using the CyberArk Credential Provider (CP):

The following diagram demonstrates how Control-M SaaS retrieves secrets from a CyberArk vault using the CyberArk Central Credential Provider (CCP):

To set up an integration with a CyberArk vault, see Setting Up a CyberArk Vault Integration.

You can use secrets from your CyberArk vault in password-type fields in centralized connection profiles for the following:

• Control-M Managed File Transfer (MFT)

• Plug-ins that you create using Control-M Application Integrator

• Control-M Integrations

During creation or configuration of a connection profile, the Use External Vault option enables you to locate and retrieve a secret for any password-type field in the connection profile parameters. See CyberArk Secret Parameters in Connection Profiles.

Setting Up a CyberArk Vault IntegrationLink copied to clipboard

This procedure describes how to set up an integration with a CyberArk vault, which includes configuring vault integration parameters and selecting the vault integrations to display in Control-M SaaS.

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

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

  • REST communication: CyberArk Central Credential Provider (CCP) version 12.1 or later

• 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.

• Use of more than one application (identified by AppID) per Agent is not recommended for security reasons.

Begin

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

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

   For backward compatibility, you can use the Vault CLI (vault-cli) utility, which was provided in previous versions of Control-M, instead of the Vault Configuration (vault-cfg) utility.

   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 CyberArk Vault integration parameters, see CyberArk Vault Integration Parameters for SDK Communication or CyberArk Vault Integration Parameters for REST Communication.

      • For certain parameters, you must recycle the Control-M plug-in (either Control-M MFT or Control-M Application Integrator) after changing the parameter value, as indicated in CyberArk Vault Integration Parameters for SDK Communication or CyberArk Vault Integration Parameters for REST Communication.

      • If you want to use your own server certificate, rather than trusting all server certificates, set the cyberark.rest.disable.trustall parameter to true (instead of the default false).

        After you create a keystore and import your server certificate in the next step, you must also configure the truststore.name, truststore.password, and truststore.type parameters.

      • 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 follows:

      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>

   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:

      CopyCopied to clipboard

      {
         "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 Connection Return Codes.

3. Select the vault integrations to appear in Control-M SaaSto use in centralized connection profiles, 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. 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 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.

CyberArk Vault Integration Parameters for SDK CommunicationLink copied to clipboard

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. For each parameter, the table indicates whether you need to recycle the component (Control-M MFT or Application Integrator) after changing the parameter value.

CyberArk Vault Integration Parameters for REST CommunicationLink copied to clipboard

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. For each parameter, the table indicates whether you need to recycle the component (Control-M MFT or Application Integrator) after changing the parameter value.

CyberArk Secret Parameters in Connection ProfilesLink copied to clipboard

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 connection profile parameters. For the retrieval of the secret, you can choose between retrieval based on default CyberArk parameters or retrieval based on a query to CyberArk.

The following parameters are available for retrieval of a secret based on default CyberArk parameters:

The following parameters are available for retrieval of a secret based on a query to CyberArk:

property1=value1;property2=value2;property3=value3

CyberArk Vault Connection Return CodesLink copied to clipboard

The following table lists return codes from connections to the CyberArk vault by either the Vault CLI utility connection test or during a job execution when Control-M attempts to locate and retrieve a secret.