CloudBees HashiCorp Vault Plugin

5 minute readSecurity

HashiCorp Vault is a secrets management system where users or vault clients can manage their sensitive details (for example, passwords, keys, certificates, and access tokens) via Secret Engines.

The CloudBees HashiCorp Vault plugin enables a credential store for CloudBees CI . Credentials are stored in a remote HashiCorp Vault instance and secrets are accessed on demand. With this plugin, you can manage credentials in a centralized location for all of your controllers.


The CloudBees HashiCorp Vault Plugin 0.6 release requires the following:

  • CloudBees CI on modern cloud platforms or CloudBees CI on traditional platforms 2.387.2.3 (or newer)

  • HashiCorp Vault v1.8.0 (or newer)

  • Controller access to the HashiCorp Vault instance

Credentials retrieval process

The following diagram illustrates the credential retrieval process.

HashiCorp Vault Credential Retrieval Process
Figure 1. HashiCorp Vault Credential Retrieval Process

Installing the HashiCorp Vault plugin

There are two options to install the HashiCorp Vault plugin:

Configuring the global HashiCorp Vault provider

The HashiCorp Vault credentials provider must be configured before you can use the HashiCorp Vault as a secret storage for your CloudBees CI instance. Once the provider is configured, it enables a new store (HashiCorp Vault) on the Credentials page. This new store is scoped to Jenkins.

Folder and user stores are not supported.

To configure a HashiCorp Vault Credentials provider:

  1. From the Dashboard, select Manage Jenkins on the left navigation pane.

  2. Under Security, select Configure Credential Providers and navigate to HashiCorp Vault Credential Provider.

    Configure Credential Providers
    Figure 2. Configure Credential Providers
  3. Enter the following details:

    View HashiCorp Vault Credential Provider details
    Label Description

    Vault URL

    The HashiCorp Vault server URL. The URL can start with http or https.

    Skip SSL Verification

    Select this option to skip SSL certificate verification. By default, this option is left blank. Leaving this option blank ensures each SSL connection to the Vault instance is secure by verifying the server’s SSL certificate. CloudBees recommend leaving this option blank.

    Vault Authentication

    The authentication required to connect to the HashiCorp Vault server. The only supported Auth Method is AppRole. The AppRole is identified by a RoleID and secured with a SecretID.

    Consider creating an AppRole as a minimal policy with read-only permission on secrets stored at the expected path. For more information, refer to Create a role with policy attached.

    AppRole configuration » Namespace (Optional)

    Enter the HashiCorp Vault namespace where secrets are stored. Leave this field blank if namespaces are not enabled or the secret is part of the root namespace.

    AppRole configuration » Role Id

    Enter the AppRole RoleID. To get the RoleID, refer to Get RoleID.

    AppRole configuration » Secret Id

    Enter the AppRole SecretID. To get the SecretID, refer to SecretID.

    By default, the SecretID generated by the HashiCorp Vault instance has a TTL (time-to-live) attribute or a num_uses attribute. Once those limitations are reached, the HashiCorp Vault credentials provider cannot retrieve secrets. CloudBees recommends configuring the AppRole with secret_id_num_uses = 0 and secret_id_ttl = 0.

  4. Select Test connection to validate the HashiCorp Vault connection details.

    • If CloudBees CI connects to the configured HashiCorp Vault instance, a Connected message displays.

    • If the connection fails, you can troubleshoot using the information contained in these error messages:

      • An error occurred while contacting Vault: invalid secret ID

      • An error occurred while contacting Vault: invalid role ID

      • An error occurred while contacting Vault: permission denied connect timed out

      • {url} nodename nor servname provided, or not known

  5. Select Save.

Configuring HashiCorp Vault credentials

After configuring the HashiCorp Vault provider, you can create two new types of credentials: Vault Username Password and Vault Secret Text. HashiCorp Vault credentials only read actual secrets from the HashiCorp Vault instance and are not used to delete, update, or create secrets.

If the HashiCorp Vault credentials need to be restricted, install the Restricted Credentials plugin.

To configure a HashiCorp Vault credential:

  1. From the Dashboard, select Manage Jenkins on the left navigation pane.

  2. Under Security, select Manage Credentials.

    Credentials page
    Figure 3. Credentials page
  3. Under Stores scoped to Jenkins, hover your cursor over the (global) domain of the HashiCorp Vault store and select Add credentials.

    Select *Add credentials*
    Figure 4. Add credentials
  4. On the New credentials page, enter details about the credential.

    New credentials page
    Figure 5. New credentials page
    View HashiCorp Vault Credentials details
    Label Description


    Select the type of credential: Vault Secret Text or Vault Username Password.

    Vault Secret Engine

    Select the appropriate type of Vault Secret Engine where secrets are stored.

    * Key/Value Secret Engine v2 is a Versioned Key/Value secret engine.

    * Key/Value Secret Engine v1 is a Static Secrets: Key/Value secret engine.

    Vault Secret Engine » Path

    Enter the path where the HashiCorp Vault secret is stored. This is a required field.

    The Vault Secret Engine validates whether the path for the HashiCorp Vault secret is correct. If the path is correct, a Path was found message displays. If CloudBees CI cannot retrieve secrets from the provided path you may receive one of the following error messages:

    * An error occurred while contacting Vault: the requested Vault resource was not found: This message displays if the path is incorrect.

    * An error occurred while contacting Vault: 1 error occurred: *permission denied. This message displays if the AppRole does not have permission to access the path.

    Vault username key

    Enter the key that points to the actual username stored in the Path field.

    Vault password key

    Enter a key that points to the actual password stored in the Path field.


    Enter a description of the credential. This is an optional field.


    Enter the credential ID. If this field is left blank, the ID is automatically generated.

  5. Select Create.

Adding a credential within a job

You can add HashiCorp Vault credentials from the configuration page of a specific job.

To create a HashiCorp Vault credential within a job:

  1. From the Dashboard, select a controller.

  2. Navigate to a specific job and select Configure from the dropdown list.

  3. Navigate to the Build Environment section and select Use secret text(s) or files(s).

    Add HashiCorp Vault credential to a job
  4. Under Bindings, select Add  Secret text.

  5. Enter details about the Secret text.

    • Variable: Enter the name of an environment variable to be set during the build.

    • Credentials: Select Specific credentials to set a specific credential type for the variable.

    • Select Add and then select a Vault Credential Provider.

Adding credentials to pipelines

Run the following commands to add a HashiCorp Vault credential to a pipeline.

  • Vault Username Password

    withCredentials([usernamePassword(credentialsId: 'vault-creds', passwordVariable: 'PASS', usernameVariable: 'USER')]) { sh 'echo USER=$USER' sh 'echo PASS=$PASS' }
  • Vault Secret Text

    withCredentials([string(credentialsId: 'vault-creds', variable: 'TOKEN')]) { sh 'echo TOKEN=$TOKEN' }

Using the HashiCorp Vault credential in CasC yaml file

You can use Configuration as Code to configure the HashiCorp Vault plugin on your CloudBees CI instance. On your controller bundle, add the following code to the jenkins.yaml file:

globalCredentialsConfiguration: vaultGlobalConfiguration: url: "http://localhost:8200" skipSslVerification: false authentication: appRoleAuthentication: namespace: "" roleId: "8e6f8a38-2171-5ef4-a503-e7dff83155f5" secretId: "74f11516-0f0c-863f-4124-30fa77535a02" credentials: cloudbeesHashicorpVault: domainCredentials: - credentials: - vaultUsernamePassword: scope: GLOBAL id: "test-username-password-id" description: "test vault username password" usernameKey: "user" passwordKey: "password" vaultSecretEngine: genericKV2SecretEngine: path: "jenkins/secrets" - vaultSecretText: scope: GLOBAL id: "test-secret-text-id" description: "test vault secret text" secretKey: "token" vaultSecretEngine: genericKV1SecretEngine: path: "jenkinsV1/secrets"