Configuring Jira with HashiCorp Vault

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

HashiCorp Vault is a secrets management platform that helps you store, access, and manage sensitive data. Jira now supports Vault as a secure storage option for your JDBC password.

Supported engines

Supported authentication

How to set up Vault

The steps below assume you already have a Hashicorp Vault instance running. For more details, see the Hashicorp Vault documentation.

To configure Jira to work with HashiCorp Vault:

  1. Create a secret in your HashiCorp Vault instance.

  2. Create a policy with permission to read your secret.

  3. Authenticate Jira with Vault.

  4. Add the Vault configuration data to the <home-directory>/dbconfig.xml file.


Important
It's quite common for Vault deployments to have a KV V2 Secret Engine enabled under the secret   mount. If you are using a different Vault deployment, please see the HashiCorp documentation for enabling a new KV V2 Secret Engine:
https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2


These steps are explained in more detail below.

Step 1: Create a secret in your HashiCorp Vault instance

If you haven’t created a secret in the KV V2 Secret Engine of your Vault instance before, take a look at the Hashicorp Vault documentation for more information.

This secret must contain a single value for your JDBC password.

Step 2: Create a policy with permission to read your secret

If you need detailed instructions on creating a policy in Vault, see the Hashicorp Vault documentation. The details below provide additional information from the Jira perspective.

To retrieve your secret from the Vault, Jira must have a policy with the read permission.

Below is a sample Vault policy with permission to read a secret in the KV V2 Secret Engine.

path "secret/data/sample/secret" {
  capabilities = ["read"]
}

In the sample path above, there are three components:

Component

Description

secret

This is where the KV V2 Secret Engine is mounted.

data

This prefix indicates this is a KV V2 secret.

sample/secret

This is the path that contains this secret.

If the previous policy is located in ./sample_policy.hcl, this command will create the policy on the server:

vault policy write sample_policy ./sample_policy.hcl

Step 3: Authenticate Jira with Vault

You can choose to authenticate with a token, or, if you’re using a Kubernetes environment, with the Kubernetes auth method. Both methods are described below.

Authenticate with a token

The information below assumes you’re familiar with creating a Vault token. Refer to the HashiCorp Vault documentation for more information and token options.

  1. Create a new token using the command:

    vault token create -policy=sample_policy
  2. To confirm that your token and policy allow access to the secret, run the commands:

    export VAULT_TOKEN=<YOUR_TOKEN>
    vault kv get -mount=secret sample/secret
  3. You should see the following output:

    ====== Secret Path ======
    secret/data/sample/secret
    
    ======= Metadata =======
    Key         Value
    ---         -----
    ~~~~        ~~~~~
    
    ====== Data ======
    Key         Value
    ---         -----
    ~~~~        ~~~~~

    If you don’t see the output above, refer to the Hashicorp documentation to troubleshoot the issue.
    To complete the process, an environment variable associated with the token must be present on Jira.

  4. Define the environment variable SECRET_STORE_VAULT_TOKEN in the context of the Jira instance. A simple way to do this is to add the following line to the ~/.bashrc file for the user running Jira:

    export SECRET_STORE_VAULT_TOKEN=<YOUR_TOKEN>


If there are any problems with your configurations (for example, the secret is not accessible with the authentication token), Jira will display details during startup, which are also available for you to check in two of your log files — catalina.out and atlassian-jira.log.


Authenticate using Kubernetes Service Account Token

If Jira is operating within a Kubernetes environment, you can leverage the Kubernetes auth method. This method uses a Kubernetes Service Account Token to confirm the identity of the pod that runs Jira and to grant the appropriate access.

Refer to the Hashicorp Vault documentation for more information on how to set up Kubernetes auth method in your Vault instance. Make sure you have enabled Kubernetes auth method on your Vault server before you start the steps below.

You will also need to set some environment variables in the following steps. The table below describes these.

Environment variable

Description

SECRET_STORE_VAULT_KUBE_AUTH_ROLE

The name of the role defined in Vault that’s attached to Kubernetes auth method.

SECRET_STORE_VAULT_KUBE_AUTH_PATH
(Optional)

The path defined in Kubernetes auth method.

The default value is:
kubernetes

SECRET_STORE_VAULT_KUBE_AUTH_JWT_PATH
(Optional)

The location of the Service Account Token file in the pod for Jira.

The default value is: /var/run/secrets/kubernetes.io/serviceaccount/token


  1. If you used custom path to create a Kubernetes auth method, replace kubernetes in the CLI command in the following step with your path name.

  2. Define a role to link the auth method with the sample_policy you created with the following command:

    vault write auth/kubernetes/role/<YOUR_NEW_ROLE_NAME> \
        bound_service_account_names=<YOUR_PRODUCT_SERVICE_ACCOUNT_NAME> \
        bound_service_account_namespaces=<YOUR_PRODUCT_SERVICE_NAMESPACE> \
        policies=sample_policy
  3. Ensure that your Jira pod has access to the secret.
    Currently, Vault CLI doesn’t offer support for logging in with Kubernetes auth method, but you can log in to retrieve client token using HTTP API and then use this generated token to test for access.

  4. If you can’t retrieve the secret with the generated token, refer to Hashicorp’s documentation to troubleshoot the issue.

  5. Refer to the table at the start of these steps to set the following environment variables for Jira:

  • SECRET_STORE_VAULT_KUBE_AUTH_ROLE

  • SECRET_STORE_VAULT_KUBE_AUTH_PATH (optional)

  • SECRET_STORE_VAULT_KUBE_AUTH_JWT_PATH (optional)

Step 4: Add the Vault configuration data to dbconfig.xml

Vault is configured via a JSON object that is added to the <home-directory>/dbconfig.xml file. The JSON configuration object has a number of fields. Make sure you refer to the following table for details on each of these properties.

We highly recommend that all your Vault instances use HTTPS to further improve security.

Field

Required?

Description

mount

Required

The KV V2 Secret Engine mount path.

path

Required

The secret path.

key

Required

The key name.

endpoint

Required

The base URL of your Vault instance.

This accepts both HTTP and HTTPS. We highly recommend you always use HTTPS.

Omit the trailing slash, if your URL has one.

authenticationType

Optional

The type of authentication you wish to use.

Supported options are TOKEN and KUBERNETES.

The default is TOKEN.

  1. In the Jira home directory, back up the dbconfig.xml file. Move the backup file to a safe place outside of your Jira server.

  2. In the dbconfig.xml file, add or modify the <atlassian-password-cipher-provider> property to contain:

    com.atlassian.secrets.store.vault.VaultSecretStore
  3. In the dbconfig.xml file, add or modify the <password> property to contain your JSON configuration object. Use the table at the start of these steps for further information on these fields.
    Here is an example of how it might look:

    {"mount": "secret", "path": "sample/secret", "key": "password", "endpoint": "https://127.0.0.1:8200"}
  4. Restart Jira

Last modified on Nov 21, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.