Secure Jenkins CI/CD secrets with HashiCorp Vault

Jenkins does not provide a single native workload identity model in the way that Kubernetes-native or hosted CI/CD platforms do. Jenkins controllers and agents can run on virtual machines, Kubernetes, or cloud-managed infrastructure, so the best Vault auth method depends on where the workload actually runs. Vault helps you reduce secret sprawl by moving external system credentials out of Jenkins credential stores and retrieving them at runtime with short-lived Vault tokens.

Traditional Jenkins credential management can still mask environment variables in logs, but it often leads to duplicated static credentials across controllers, folders, and pipelines. Authorization decisions also stay tied to Jenkins-managed credentials rather than Vault policies scoped to secret paths. Vault shifts authorization to externally authenticated identities and lets each pipeline retrieve the secrets it needs for the job it is running.

Architecture

The pipeline-to-Vault authentication flow follows the same high-level pattern regardless of auth method, but the verification step differs by method:

The Jenkins agent presents an identity to Vault
Vault validates that identity directly or through the relevant platform
Vault maps the validated identity to a role
Vault issues a token scoped to the policies attached to that role

Unlike CI/CD platforms that provide a native workload identity model (such as GitHub Actions OIDC or GitLab JWT), Jenkins has no single preferred auth method. These steps describe the general Vault authentication flow. The specific method your pipeline uses depends on where your Jenkins agents run. Refer to Where Jenkins runs affects auth method selection for details.

Diagram showing authentication workflow between workloads like Jenkins, to
Vault, to the platform identity provider

Where Jenkins runs affects auth method selection

Jenkins controllers usually orchestrate work, but Jenkins agents execute the pipeline steps that need secrets. For that reason, the agent runtime should determine the Vault auth method:

If agents run on Kubernetes, use Kubernetes auth.
If agents run on AWS, Azure, or GCP with native machine identity, use the corresponding cloud auth method.
If agents run on long-lived VMs or bare metal in a private environment, use AppRole or TLS cert auth.
If agents run on a platform that can issue OIDC-compatible workload tokens, use JWT/OIDC auth.

The Jenkins Vault plugin, the CloudBees HashiCorp Vault plugin, Jenkins credentials binding, and Vault Agent sidecars affect how agents retrieve secrets and mask them in pipelines. Those integrations do not change the underlying identity model. Pick the auth method based on the agent runtime, then decide how Jenkins should consume the resulting Vault token and secrets.

Authentication options

Because Jenkins can run in many environments, no single auth method fits every deployment. Use the auth method that matches the most authoritative identity the agent already has.

Jenkins integrates with Vault through the following patterns:

The Jenkins Vault plugin provides declarative secret retrieval and masks retrieved secrets in pipeline logs, making it a practical option when teams want plugin-managed secret access.
The CloudBees HashiCorp Vault plugin provides a similar pattern for CloudBees CI controllers that follow the same underlying Vault auth model and use the plugin as the Jenkins integration layer.
Jenkins credentials binding can protect bootstrap material such as VAULT_ADDR, wrapped AppRole tokens, and certificate paths when you call the Vault API or CLI directly. This is useful when jobs need flexible secret retrieval across different paths, structured secret layouts, or tenancy boundaries rather than plugin-managed bindings.
Vault Agent sidecars work well on ephemeral agents and reduce Jenkins plugin dependencies, which makes them a strong fit for containerized workloads, but file-rendered secrets are not automatically masked in Jenkins logs.

The following table summarizes when each auth method fits best.

Auth method	Security posture	Credential lifecycle	Best suited for
JWT / OIDC	High; identity federates across trust boundaries	Token issued per job or workload, typically short-lived	Jenkins agents running on platforms that can issue OIDC-compatible workload tokens
Cloud provider auth methods	High when bound to native cloud identity	Short-lived cloud identity or metadata-backed login	Jenkins agents running on AWS, Azure, or GCP
Kubernetes	Highest for in-cluster	Short-lived projected token on modern Kubernetes; legacy patterns vary	Jenkins agents running as pods in Kubernetes
TLS Certificate	High; mutual authentication	Certificate with defined expiry; requires rotation process	Long-lived Jenkins agents where mTLS is already part of the security posture
AppRole	Moderate; requires secure secret ID delivery	Secret ID is single-use with response wrapping; RoleID is long-lived	Traditional self-hosted Jenkins agents where no stronger platform identity exists

JWT/OIDC auth is the right choice when Jenkins agents run on a platform that can issue OIDC-compatible workload tokens. Jenkins itself does not issue these tokens natively, so this pattern depends on the surrounding platform, workload identity broker, or federation layer.

Role configuration

The security-critical configuration here is workload-specific role constraints. bound_claims is the most flexible option, but you can also use constraints such as bound_audiences and bound_subject. Without these restrictions, a broader set of issuer-valid JWTs may authenticate than you intend.

# Vault JWT role with workload-specific claim bindings
vault write auth/jwt/role/jenkins-deploy \
  role_type=jwt \
  bound_audiences="https://vault.example.com" \
  bound_claims='{"sub": "jenkins-agent-prod", "pipeline": "deploy"}' \
  user_claim=sub \
  token_policies=jenkins-deploy-policy \
  ttl=15m

Workflow configuration

The example assumes an external identity component writes a short-lived JWT to the agent filesystem before the build step runs.

pipeline {
  agent any

  environment {
    WORKLOAD_JWT_FILE = '/var/run/jenkins/workload/token'
  }

  stages {
    stage('Read secret from Vault') {
      steps {
        sh '''
          JWT="$(cat "$WORKLOAD_JWT_FILE")"
          VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=jenkins-deploy jwt="$JWT")"
          API_KEY="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=key secret/ci/production/api)"
          ./deploy.sh
        '''
      }
    }
  }
}

The agent reads the short-lived workload token from the local filesystem, exchanges it for a Vault token, and retrieves only the secret required for the deployment.

Use cloud provider auth methods when Jenkins agents run on cloud VMs or managed compute that already have native cloud identity. This avoids storing cloud credentials in Jenkins to bootstrap Vault login.

AWS auth is appropriate for Jenkins agents running on EC2 or other AWS compute with an instance profile or IAM role. Prefer the iam auth type for most Jenkins use cases.

Role configuration

The primary control is binding the Vault role to the expected IAM principal ARN.

# Vault AWS role — bound to the Jenkins agent instance profile role
vault write auth/aws/role/jenkins-aws \
  auth_type=iam \
  bound_iam_principal_arn="arn:aws:iam::123456789012:role/jenkins-agent-role" \
  token_policies=jenkins-build-policy \
  ttl=1h

Workflow configuration

The example assumes the Jenkins agent already has AWS credentials from its instance profile or workload role.

pipeline {
  agent any

  stages {
    stage('Read secret from Vault') {
      steps {
        sh '''
          VAULT_TOKEN="$(vault login -method=aws -token-only \
            header_value=vault.example.com \
            role=jenkins-aws)"
          DB_PASSWORD="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=password secret/ci/production/db)"
          ./build.sh
        '''
      }
    }
  }
}

The agent authenticates with its AWS identity and retrieves only the secret it needs for the build. This avoids storing a bootstrap credential in Jenkins.

Azure auth is appropriate for Jenkins agents running on Azure VMs or other Azure resources with managed identities.

Role configuration

The role should bind to the expected Azure subscription, resource group, and service principal or managed identity.

# Vault Azure role — bound to the Jenkins agent managed identity
vault write auth/azure/role/jenkins-azure \
  token_policies=jenkins-build-policy \
  bound_subscription_ids="6a1d5988-5917-4221-b224-904cd7e24a25" \
  bound_resource_groups="jenkins-runners" \
  bound_service_principal_ids="3cb88732-1356-4782-b671-4877166be01a" \
  ttl=1h

Workflow configuration

The example assumes the Jenkins agent can query the Azure Instance Metadata Service for its managed identity token and instance metadata.

pipeline {
  agent any

  stages {
    stage('Read secret from Vault') {
      steps {
        sh '''
          JWT="$(curl -s 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.azure.com%2F' -H Metadata:true | jq -r '.access_token')"
          # bound_service_principal_ids is set on the role — no VM metadata required
          VAULT_TOKEN="$(vault write -field=token auth/azure/login role=jenkins-azure jwt="$JWT")"
          API_KEY="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=key secret/ci/production/api)"
          ./deploy.sh
        '''
      }
    }
  }
}

The agent retrieves an Azure access token from IMDS, exchanges it for a Vault token, and reads only the secret needed for the deployment.

GCP auth is appropriate for Jenkins agents running on Google Cloud. For most Jenkins use cases, iam roles bound to service accounts are the most direct fit.

Role configuration

The primary control is binding the Vault role to the expected Google Cloud service account.

# Vault GCP role — bound to the Jenkins agent service account
vault write auth/gcp/role/jenkins-gcp \
  type="iam" \
  token_policies="jenkins-build-policy" \
  bound_service_accounts="jenkins-agent@my-project.iam.gserviceaccount.com" \
  ttl=1h

Workflow configuration

The example assumes the Jenkins agent runs on Google Cloud with a service account that can mint the JWT required by Vault.

pipeline {
  agent any

  stages {
    stage('Read secret from Vault') {
      steps {
        sh '''
          VAULT_TOKEN="$(vault login -method=gcp -token-only role=jenkins-gcp)"
          REGISTRY_PASSWORD="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=password secret/ci/build/registry)"
          ./build.sh
        '''
      }
    }
  }
}

The agent logs in with its Google Cloud identity instead of using a bootstrap credential stored in Jenkins. The resulting Vault token is then used only for the required secret read.

Kubernetes auth is appropriate when Jenkins agents run as pods in Kubernetes. The agent pod's service account token is already present, and Vault can verify that identity against the Kubernetes API without introducing an extra bootstrap credential.

Role configuration

The role definition enforces which Kubernetes namespaces and service accounts Vault allows to authenticate, making this the primary control against one agent pod impersonating another.

# Vault role — binds to a specific service account and namespace
vault write auth/kubernetes/role/jenkins-agent \
  bound_service_account_names=jenkins-build-sa \
  bound_service_account_namespaces=jenkins-agents \
  token_policies=jenkins-build-policy \
  ttl=1h

Workflow configuration

The example assumes the Jenkins Kubernetes plugin launches the agent pod with a dedicated service account.

pipeline {
  agent {
    kubernetes {
      yaml '''
apiVersion: v1
kind: Pod
spec:
  serviceAccountName: jenkins-build-sa
'''
    }
  }

  stages {
    stage('Read secret from Vault') {
      steps {
        sh '''
          VAULT_TOKEN="$(vault write -field=token auth/kubernetes/login \
            role=jenkins-agent \
            jwt=@/var/run/secrets/kubernetes.io/serviceaccount/token)"
          REGISTRY_PASSWORD="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=password secret/ci/build/registry)"
          ./build.sh
        '''
      }
    }
  }
}

The agent authenticates with the pod's projected service account token and retrieves only the secret required for the build. This keeps the trust boundary inside the Kubernetes cluster.

TLS cert auth applies when Jenkins agents are long-lived systems and client certificates are already part of the infrastructure security posture.

Role configuration

Trust in the issuing CA is the primary control in cert auth. CN or SAN restrictions then narrow authentication to the specific certificate subjects you expect.

# Vault TLS cert role for a named Jenkins agent fleet
vault write auth/cert/certs/jenkins-agent-fleet \
  display_name=jenkins-agent-fleet \
  certificate=@/path/to/internal-ca.crt \
  allowed_common_names="jenkins-agent-*.infra.example.com" \
  token_policies=jenkins-agent-policy \
  ttl=4h

Workflow configuration

The pattern assumes the agent certificate and private key are provisioned on the Jenkins agent by your PKI workflow.

pipeline {
  agent any

  stages {
    stage('Read secret from Vault') {
      steps {
        sh '''
          VAULT_TOKEN="$(vault login -method=cert -token-only \
            name=jenkins-agent-fleet \
            -client-cert=/etc/vault/tls/client.crt \
            -client-key=/etc/vault/tls/client.key)"
          SIGNING_KEY="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=key secret/ci/build/signing)"
          ./sign.sh
        '''
      }
    }
  }
}

The agent authenticates with its client certificate and retrieves only the secret needed for the signing workflow. This pattern fits persistent agents that already participate in an mTLS-based operating model.

AppRole is the right default when Jenkins agents run on self-hosted VMs or bare metal and no stronger workload identity is already available.

Role configuration

The critical operational concern with AppRole is secure initial delivery of the secret_id. Always use response wrapping so the secret_id is delivered as a single-use wrapping token.

Without response wrapping, AppRole delivery in Jenkins often degrades into long- lived bootstrap credentials stored in Jenkins credential stores, which weakens the security model.

# Vault AppRole role — short TTL on secret_id, single use
vault write auth/approle/role/jenkins-build \
  secret_id_ttl=10m \
  secret_id_num_uses=1 \
  token_ttl=1h \
  token_max_ttl=2h \
  token_policies=jenkins-build-policy

The AppRole configuration constrains bootstrap material to short-lived, single-use delivery and limits the Vault token lifetime for the job.

Workflow configuration

Jenkins credentials binding can hold the RoleID and the single-use wrapping token while the pipeline unwraps the secret_id at runtime. In some environments, an external privileged process such as an administrative pipeline, an init workflow, or a Vault Agent running on the controller can generate that wrapping token and place it in Jenkins credentials before the job starts.

pipeline {
  agent any

  stages {
    stage('Read secret from Vault') {
      steps {
        withCredentials([
          string(credentialsId: 'vault-role-id', variable: 'VAULT_ROLE_ID'),
          string(credentialsId: 'vault-secret-id-wrap', variable: 'VAULT_WRAP_TOKEN')
        ]) {
          sh '''
            SECRET_ID="$(VAULT_TOKEN="$VAULT_WRAP_TOKEN" vault unwrap -field=secret_id)"
            VAULT_TOKEN="$(vault write -field=token auth/approle/login role_id="$VAULT_ROLE_ID" secret_id="$SECRET_ID")"
            DB_PASSWORD="$(VAULT_TOKEN="$VAULT_TOKEN" vault kv get -field=password secret/ci/production/db)"
            ./deploy.sh
          '''
        }
      }
    }
  }
}

The pipeline unwraps the single-use secret_id just before login and exchanges it for a short-lived Vault token. The job then uses that token only for the secret reads authorized by the AppRole policy.

Policy

The Vault policy for any role should follow least privilege. A pipeline that deploys to production should not be able to read staging secrets, and a staging pipeline should not be able to read production secrets.

An example Vault policy for a production deployment pipeline might look like this:

# Vault policy: scope to exactly the paths this pipeline needs
path "secret/data/ci/production/db" {
  capabilities = ["read"]
}

# Deny access to everything else implicitly

The policy limits the job to the exact production secret path it needs. Use separate policies for other environments and job types so unrelated pipelines do not inherit broader access.

Dynamic secrets are a strong fit for Jenkins because the pipeline can retrieve database credentials, Terraform tokens, or cloud credentials immediately before use and discard the Vault token when the stage completes. This keeps short-lived credentials out of long-lived Jenkins credential stores while still fitting common Jenkins patterns such as plugin-based retrieval, direct API calls, or agent-local Vault workflows. In plugin-based pipelines, the Jenkins Vault plugin or CloudBees HashiCorp Vault plugin can surface these short-lived values as job-scoped environment variables while masking retrieved secrets in logs.

Security considerations

There are several Jenkins-specific security considerations you need to align with your organizational risk tolerance and operational constraints when designing your CI/CD secrets management strategy:

Agent-scoped identities: Authenticate from the Jenkins agent that needs the secret, not from the controller on behalf of every job. This preserves workload-level separation and reduces lateral movement risk.
Secret masking limitations: The Jenkins Vault plugin can mask retrieved secrets in logs, but direct API calls and Vault Agent-rendered files are not automatically masked. Avoid echoing secrets, dumping environments, or passing secrets to verbose commands.
AppRole delivery controls: If you use AppRole, always deliver secret_id values through single-use wrapping tokens. A raw secret_id stored in Jenkins credentials becomes a bootstrap secret that must be protected like any other long-lived credential.
Shared agent isolation: Do not reuse workspaces, home directories, or cached token files across unrelated jobs on shared agents. A leftover Vault token on disk can expose another pipeline's secrets.

For a list of additional security considerations, refer to the CI/CD security considerations page.

Integrate HCP Vault Radar

Before migrating to Vault-based secrets management, Vault Radar can scan Jenkins pipeline definitions, shared libraries, and connected repositories for credentials stored as hardcoded values. This is particularly important in organizations that have accumulated years of Jenkinsfiles, helper scripts, and folder-level credentials across many teams.

After migration, Vault Radar can monitor your source code repositories continuously for new secret introductions — catching cases where developers add static tokens or passwords to Jenkinsfiles instead of retrieving them from Vault.

Refer to the HCP Vault Radar quick start tutorials to learn about HCP Vault Radar.

HashiCorp resources

Vault

Read the Auth methods documentation to choose the right Vault authentication method for your Jenkins environment.
Read the Response wrapping documentation to learn how to deliver single-use secret IDs securely.
Read the Vault Agent documentation to configure Vault Agent for automatic secret injection in Jenkins pipelines.
Follow the Dynamic secrets: database credentials tutorials to generate short-lived database credentials from Vault.
Follow the Generate cloud provider credentials with Vault tutorial to issue temporary cloud provider credentials for pipeline jobs.

HCP Vault Radar

Read What is HCP Vault Radar for an overview of how Vault Radar scans for exposed secrets.
Follow the Get started with HCP Vault Radar tutorial to enable continuous scanning for your repositories.

External resources

Read the Jenkins HashiCorp Vault plugin documentation to configure Vault secret retrieval in Jenkins pipelines.
Read the CloudBees HashiCorp Vault plugin documentation for CloudBees CI-specific Vault integration guidance.
Read the Jenkins Pipeline syntax reference to understand pipeline configuration options used in the examples.
Read Secure CI/CD pipeline secrets in Jenkins on Kubernetes for example code demonstrating Vault-based secret management for Jenkins on Kubernetes.

Next steps

In this section of managing CI/CD secrets, you learned how to choose Vault auth methods for Jenkins based on where agents run and how to scope secrets to individual jobs. Secure Jenkins CI/CD secrets with HashiCorp Vault is part of the Secure systems pillar.

If your Jenkins agents already run on Kubernetes or cloud-managed compute, prefer those native platform identities over AppRole to reduce bootstrap secret distribution. If you're deciding between static and dynamic secret models for pipeline use, review CI/CD dynamic and static secrets.