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 Control-M/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.

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

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:

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 Integration

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

Before You Begin

  • Verify that CyberArk CP version or 12.1 or later is installed and configured on the Control-M/Agent host machine.

  • Verify that Control-M/EM 9.0.21.300 or higher is installed.

Begin

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

  2. Run the Vault CLI utility and configure the integration for each relevant Control-M plug-in or group of plug-ins, as follows:

    1. Navigate to the directory that contains the Vault CLI utility for the relevant plug-in or group of plug-ins:

      • Control-M MFT: <AGENT_HOME>/ctm/cm/AFT/exe/

      • Application Integrator plug-ins: <AGENT_HOME>/ctm/cm/AI/exe/

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

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

      • Windows: vault-cli.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.

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

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

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

        • Windows: vault-cli.cmd config display

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

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

        • Windows: vault-cli.cmd config delete

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

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

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

You must type all parameter names in lowercase.

Parameter

Description

Recycle Required?

provider.name

Determines the vault provider and enables vault integration.

For integration with a CyberArk vault, set the value to cyberark

Mandatory. No default.

Yes

cyberark.connection.port

Defines the CyberArk Credential Provider connection port.

Default: 18923

No

cyberark.connection.timeout

Determines the number of seconds to wait before the CyberArk Credential Provider connection times out.

Default: 30

No

cyberark.sdk.path

Defines the path to the directory that contains the CyberArk Credential Provider Java SDK, javapasswordsdk.jar (in Linux) or JavaPasswordSDK.jar (in Windows).

Supported CyberArk Credential Provider versions are 12.1 or later.

Default:

  • Linux: /opt/CARKaim/sdk

  • Windows: <CP_installation_path>\CyberArk\ApplicationPasswordSdk

Yes

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

Parameter

Description

Vault Integration

Determines one of the following vault types and/or methods to locate and retrieve the secret:

  • CyberArk Vault: Defines default CyberArk parameters.

  • CyberArk Vault - Query Based: Enables you to include additional CyberArk parameters.

AppID

Defines the unique ID of the application that issues the password request.

Maximum length: 128

Safe

Defines the name of the CyberArk Safe where the password is stored.

Maximum length: 28

Folder

(Optional) Defines the name of the folder where the password is stored.

Maximum length: 160

Default: Root

Account

Defines the name of the account (that is, the object name) to retrieve.

Maximum length: 165

Reason

(Optional) Defines the reason for the request.

Maximum length: 344

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

Parameter

Description

Vault Integration

Determines one of the following vault types and/or methods to locate and retrieve the secret:

  • CyberArk Vault: Defines default CyberArk parameters.

  • CyberArk Vault - Query Based: Enables you to include additional CyberArk parameters.

AppID

Defines the unique ID of the application that issues the password request.

Maximum length: 128

Query

Defines a query for the location and retrieval of the secret. This query enables you to include additional CyberArk properties.

Maximum length: 2048 characters

The query has the following format:

Copy
property1=value1;property2=value2;property3=value3

Safe=financeDep;title=Sr;Department=IT

  • The query must uniquely define a single secret.

  • For more information about properties that you can include in the query, see CyberArk Documentation.

  • Properties and values are subject to CyberArk restrictions.

  • The query format is Exact. Regular expressions are not supported.

Reason

(Optional) Defines the reason for the request.

Maximum length: 344

CyberArk Vault Connection Return Codes

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.

Return Code

Description

0

Success (Ended OK)

1

General error

2

Incorrect use of shell builtins (for example, incorrect number of arguments)

11

Unexpected parameter

12

Mandatory parameter is missing

13

Type of vault integration is missing

20

Unsupported vault provider

21

Vault integration is not enabled on this component; the provider.name parameter is not set

30

Wrong SDK path

31

Failed to get the vault secret.

This return code might be accompanied by errors returned from the vault provider. For a list of errors from CyberArk, see the list of Application Provider Messages in CyberArk Documentation.

32

Wrong configuration parameter

41

Regular password, not Vault Secret Locator

51

Missing file permissions

90

General error