HashiCorp Vault Integration

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

Control-M communicates with the HashiCorp Enterprise Vault via a REST call, as shown in the following diagram:

Control-M communication with the HashiCorp Enterprise Vault supports a wide variety of authentication methods.

Setting Up a HashiCorp Vault Integration

This procedure describes how to set up a HashiCorp 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 a HashiCorp Enterprise Vault and have the URL and reachable network path to access it.

  • Ensure that you have the following vault configuration items:

    • Details of vault authentication.

    • Proxy details, if outbound access goes through a proxy.

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 HashiCorp Vault Integration Parameters.

      • 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 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:HashiCorp:Vault",
          "Application": "finance",    
          "Key": "emuser",
          "SecretURL": "v1/kv/data/onecm/emuser"
      }

      These parameters are described in HashiCorp 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 Vault Connection Return Codes.

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

HashiCorp Vault Integration Parameters

The following table lists the HashiCorp Vault integration parameters that you can configure using the Vault Configuration utility.

  • You must type all parameter names in lowercase.

  • Certain parameters are defined separately per application. An application is a logical entity that enables you to set different HashiCorp credentials for sub-groups (such as business units or departments).

    You want different credentials for your HR department and your Finance department:

    • Set a Token connection for the HR department, by defining the token name as the value of the hashicorp.hr.token.token parameter.

    • Set a UserPass connection for the Finance department, by setting values for the hashicorp.finance.userpass.user and hashicorp.finance.userpass.password parameters.

    Later, when you define the secret (as described in HashiCorp Secret Parameters in Connection Profiles), set the Application parameter to either HR or Finance.

Parameter

Description

Auth

provider.name

Determines the vault provider and enables vault integration.

For integration with a HashiCorp vault, set the value to hashicorp

Mandatory. No default.

All

communication.type

Defines the type of communication with HashiCorp.

For integration with a HashiCorp vault, set the value to rest

Mandatory. Default (SDK) not compatible with HashiCorp.

All

hashicorp.rest.baseurl

Defines the authentication endpoint base URL for communication with the HashiCorp Enterprise Vault.

https://vault.example.com:8200

All

hashicorp.<app>.authtype

Determines one of the following authentication methods to use for a specific application:

  • Token

  • UserPass

  • AppRole

  • Radius

  • Ldap

  • TlsCertificate

  • Jwt

  • GitHub

All

hashicorp.rest.login.<authtype>

Defines the authentication HashiCorp login endpoint for each authentication type that you use with any of your applications.

v1/auth/userpass/login

All

hashicorp.<app>.token.token

Defines the token used for a specific application in the Token authentication method.

Token

hashicorp.<app>.userpass.user

Defines the username for UserPass authentication of a specific application.

UserPass

hashicorp.<app>.userpass.password

Defines the password for UserPass authentication of a specific application.

UserPass

hashicorp.<app>.approle.role_id

Defines the role ID for AppRole authentication of a specific application.

AppRole

hashicorp.<app>.approle.secret_id

Defines the secret ID for AppRole authentication of a specific application.

AppRole

hashicorp.<app>.radius.user

Defines the username for Radius authentication of a specific application.

Radius

hashicorp.<app>.radius.password

Defines the password for Radius authentication of a specific application.

Radius

hashicorp.<app>.ldap.user

Defines the username for Ldap authentication of a specific application.

Ldap

hashicorp.<app>.ldap.password

Defines the password for Ldap authentication of a specific application.

Ldap

hashicorp.<app>.tlscertificate.user

Defines the username for TlsCertificate authentication of a specific application.

For this type of authentication, you provide one of the following parameter combinations:

  • Names of required PEM files—CA cert, cert, and key

  • Details of the keystore that contains the PEM files—name, type, and password

TlsCertificate

hashicorp.<app>.tlscertificate.keystore_name

Defines the keystore name for TlsCertificate authentication of a specific application.

keystore.p12

TlsCertificate

hashicorp.<app>.tlscertificate.keystore_type

Determines the keystore type for TlsCertificate authentication of a specific application.

Values:

  • JKS

  • PKCS12

Default: PKCS12

TlsCertificate

hashicorp.<app>.tlscertificate.keystore_password

Defines the keystore password for TlsCertificate authentication of a specific application.

TlsCertificate

hashicorp.<app>.tlscertificate.cacertpem

Defines the name of the PEM-formatted CA cert file for TlsCertificate authentication of a specific application.

TlsCertificate

hashicorp.<app>.tlscertificate.certpem

Defines the name of the PEM-formatted cert file for TlsCertificate authentication of a specific application.

TlsCertificate

hashicorp.<app>.tlscertificate.keypem

Defines the name of the PEM-formatted key file for TlsCertificate authentication of a specific application.

TlsCertificate

hashicorp.<app>.jwt.role

Defines the JSON Web Token (JWT) role for authentication of a specific application.

Jwt

hashicorp.<app>.jwt.token

Defines the JSON Web Token (JWT) for authentication of a specific application.

Jwt

hashicorp.<app>.github.token

Defines the GitHub token for authentication of a specific application.

GitHub

proxy.host

Defines the hostname of the proxy server used to communicate with the HashiCorp vault.

Mandatory if communication with HashiCorp goes through a proxy server.

All

proxy.port

Determines the number of the designated port on the proxy server used to communicate with the HashiCorp vault.

Mandatory if communication with HashiCorp goes through a proxy server.

All

proxy.user

Defines the username for optional authentication of communication through the proxy server.

All

proxy.password

Defines the password for optional authentication of communication through the proxy server.

All

proxy.nonProxyHosts

Defines an optional comma-separated list of specific hosts to exclude from communication through the proxy server.

All

rest.disable.trustall

Determines whether to disable trust of all server certificates.

Set this parameter to true if you want to use your own server certificate, instead of trusing all server certificates.

Values:

  • true

  • false

Default: false

All

truststore.name

Defines the truststore name.

All

truststore.password

Defines the truststore password.

The password is encrypted.

All

truststore.type

Defines the truststore type.

Values:

  • JKS

  • PKCS12

Default: PKCS12

All

HashiCorp Secret Parameters in Connection Profiles

The following table describes the parameters that are used to locate and retrieve passwords or secrets from a HashiCorp 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.

Parameter

Description

Application

Defines the name of an application, as defined in application-specific HashiCorp Vault Integration Parameters.

An application is a logical entity that enables you to set different HashiCorp credentials for sub-groups (such as business units or departments).

Secret URL

Defines the path to the secret in the HashiCorp vault, relative to the base URL (which is defined by the hashicorp.rest.baseurl integration parameter).

If the full URL is https://vault.example.com:8200/v1/kv/data/secrets/secret, set Secret URL to the following value:

v1/kv/data/secrets/secret

Key

Defines the key of the secret in the HashiCorp vault.

The value of this key is the secret.