Configuring Pipelines with user-scoped credentials

It’s best practice to limit the use of privileged credentials in a Pipeline; however, global credentials are accessible to everyone and if you add credentials at the folder level for a project, all users with access to the folder will have access to the sensitive credentials.

Using user-scoped credentials in a Pipeline can limit privileged credentials use to specific tasks within a Pipeline. Furthermore, user-scoped credentials are only accessible if the user who owns the credentials has explicitly bound those credentials to a build, for instance as part of a parameterized build or input step. Therefore, team admins can configure a Pipeline to require credentials, and also require that the user authenticate to prove that they have the right to use the privileged credentials.

To configure Pipelines with user-scoped credentials:

Users who need to authorize a build or certain steps in a Pipeline add their personal credentials to their user account.
The Pipeline job is parameterized or an input step is added and the user’s credential is bound to a parameter name for those steps.
A reference to the credential using the parameter name is added to the Pipeline using withCredentials() or other steps that take a credential ID.
When the Pipeline runs or when the Pipeline reaches the input step, the user is prompted to select the required credentials and will now have the option to include user-scoped credentials.

Any user-scoped credentials used in a Pipeline are only accessible for the life of that Pipeline run/build. They are not automatically propagated to a build within a build step.

Prerequisites

Credentials plugin, minimum version: 2.3.0
Pipeline: Input Step plugin, minimum version: 2.11
Pipeline: Groovy plugin
Pipeline: Job plugin

Adding user-scoped credentials to your user account

To add user-scoped credentials to your user account:

Log in to the Admin Dashboard.
Click on your user name in the top navigation pane.
Click Credentials in the left navigation pane.
Click the (global) link.
Click Add Credentials.
Select the credentials Kind.

Any credentials Kind will work for this step.
Enter the credentials details.
Click OK.

Configuring user-scoped credentials as a build parameter

To require authorized users to enter their user-scoped credentials before a Pipeline can begin executing, you need to add a placeholder for the user’s credentials to the parameters within the Pipeline properties and withCredentials() or environment section within the build stage that references those credentials in your Scripted or Declarative Pipeline as illustrated below.

Sample Pipeline with user-scoped credentials as a build parameter

pipeline {
  agent any
  // build parameters can insert user credentials for the entire pipeline
  parameters {
    credentials(credentialType: 'com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl',
                defaultValue: '',
                description: 'Production deployment key',
                // the credentials name used here must match the parameter passed to userColonPassword in the 'Deploy' stage below
                name: 'deployKey',
                required: true)
  }
  stages {
    stage('Build') {
      steps {
        sh './build.sh'
      }
    }
    stage('Deploy') {
      environment {
        // the usernameColorPassword must be passed the credential name in the Pipeline parameters above
        DEPLOY_KEY = usernameColonPassword('deployKey')
      }
      steps {
        sh 'curl -u "$DEPLOY_KEY" -XPOST https://webhooks.example.com/promote/'
      }
    }
  }
}▼

properties([
  parameters([
    credentials(credentialType: 'com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl',
                defaultValue: '',
                description: 'Production deployment key',
                // the credentials name used here must match the credentialsId referenced in the 'Deploy' stage below
                name: 'deployKey',
                required: true)
  ])
])

node {
  stage('Build') {
    sh './build.sh'
  }
  stage('Deploy') {
    withCredentials([
      // the credentialsId must match the credential name in the Pipeline properties parameters above
      usernameColonPassword(credentialsId: 'deployKey', variable: 'DEPLOY_KEY')
    ]) {
      sh 'curl -u "$DEPLOY_KEY" -XPOST https://webhooks.example.com/promote/'
    }
  }
}▼

The syntax used in the example above is available starting with version 2.3 of the Credentials plugin. For previous versions of the Credentials plugin, use credentialsId: ${deployKey}. It is also worth noting that in Declarative Pipelines, each parameter’s value is its own "line" or groovy statement and in Scripted Pipelines, parameters() are a list, so you need commas for additional entries.

For simplicity, it is recommended that you use the Pipeline Syntax Generator to generate the entire properties() section for a Scripted Pipeline.

Before the Pipeline will begin, a message will request the required credentials be supplied before proceeding. To select user-scoped credentials, you must check the List user credentials checkbox. Once checked, a warning will remind users to only provide user credentials to trusted builds.

You should not select this option unless you have reviewed and trust this Pipeline. To ensure the Pipeline is a trusted Pipeline, check the URL to make sure it leads to the page you are expecting.

Select user-scoped credentials for build

Configuring user-scoped credentials as an input step

To require authorized users to enter their user-scoped credentials before a portion of your Pipeline can complete, you need to add a placeholder for the user’s credentials to an input step that references those credentials using withCredentials() in your Scripted or Declarative Pipeline as illustrated below.

Sample Pipeline with user-scoped credentials as an input step

pipeline {
  agent none
  stages {
    stage('Build') {
      agent any
      steps {
        sh './build.sh'
      }
    }
    stage('Deploy') {
      agent any
      // user credentials as an input step (doesn't prompt for credentials until executing this stage)
      input {
        message 'Select deployment credentials'
        parameters {
          credentials(credentialType: 'com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl',
                      defaultValue: '',
                      description: 'Production deployment key',
                      // the credentials name used here must match the parameter passed to userColonPassword below
                      name: 'deployKey',
                      required: true)
        }
      }
      environment {
        // usernameColorPassword must be passed the credential name in the input parameters above
        DEPLOY_KEY = credentials('deployKey')
      }
      steps {
        sh 'curl -u "$DEPLOY_KEY" -XPOST https://webhooks.example.com/promote/'
      }
    }
  }
}▼

stage('Build') {
  node {
    sh './build.sh'
  }
}
stage('Deploy') {
    // we can use an input step to insert user credentials when needed
  input message: 'Select deployment credentials', parameters: [
    credentials(credentialType: 'com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl',
                defaultValue: '',
                description: 'Production deployment key',
                // the credentials name used here must match the credentialsId referenced below
                name: 'deployKey',
                required: true)
  ]
  node {
    withCredentials([
      // the credentialsId must match the credential name in the input message credentials above
      usernameColonPassword(credentialsId: 'deployKey', variable: 'DEPLOY_KEY')
    ]) {
      sh 'curl -u "$DEPLOY_KEY" -XPOST https://webhooks.example.com/promote/'
    }
  }
}▼

For simplicity, it is recommended that you use the Pipeline Syntax Generator to generate the entire properties() section for a Scripted Pipeline.

When the Pipeline gets to the input step indicated, a message will request the required credentials be supplied before proceeding. To select user-scoped credentials, you must check the List user credentials checkbox. Once checked, a warning will remind users to only provide user credentials to trusted builds.

You should not select this option unless you have reviewed and trust this Pipeline. To ensure the Pipeline is a trusted Pipeline, check the URL to make sure it leads to the page you are expecting.