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:

  1. Users who need to authorize a build or certain steps in a Pipeline add their personal credentials to their user account.

  2. 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.

  3. A reference to the credential using the parameter name is added to the Pipeline using withCredentials() or other steps that take a credential ID.

  4. 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:

  1. Log in to the Admin Dashboard.

  2. Click on your user name in the top navigation pane.

  3. Click Credentials in the left navigation pane.

  4. Click the (global) link.

  5. Click Add Credentials.

  6. Select the credentials Kind.

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

  8. 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

// Declarative //
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/'
      }
    }
  }
}
// Script //
// build parameters can insert user credentials for the entire pipeline
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/'
    }
  }
}
In Declarative Pipelines, each parameters value is its own "line" , or groovy statement. 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

// Declarative //
pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh './build.sh'
      }
    }
    stage('Deploy') {
      // 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 = usernameColonPassword('deployKey')
      }
      steps {
        sh 'curl -u "$DEPLOY_KEY" -XPOST https://webhooks.example.com/promote/'
      }
    }
  }
}
// Script //
node {
  stage('Build') {
    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)
    ]
    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/'
    }
  }
}
In Declarative Pipelines, each parameters value is its own "line" , or groovy statement. 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.

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.
Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.