Jenkins Credentials Binding Plugin

External

• https://wiki.jenkins.io/display/JENKINS/Credentials+Binding+Plugin
• https://plugins.jenkins.io/credentials-binding/
• https://www.jenkins.io/doc/pipeline/steps/credentials-binding/#withcredentials-bind-credentials-to-variables
• https://docs.cloudbees.com/docs/cloudbees-ci/latest/cloud-secure-guide/injecting-secrets

Internal

• Jenkins Security Concepts
• Jenkins Pipeline Syntax | withCredentials

Overview

This plugin allows credentials defined in the Jenkins server to be bound to environment variables or Groovy variables to be used fro miscellaneous build steps, inside a closure. It uses a withCredentials step whose programming model is explained below. The advantage of using this pattern is that the credentials are maintained securely by the Jenkins instance and they are automatically masked in the logs.

Playground

https://github.com/ovidiuf/playground/tree/master/jenkins/pipelines/credentials-binding-plugin

withCredentials

The step can be configured with a binding list and executes a closure within which the credentials are projected:

withCredentials(<binding-list>) {
  // closure
}

The following bindings are available:

• usernamePassword
• sshUserPrivateKey
• certificate
• dockerCert
• file
• kubeconfigContent
• kubeconfigFile
• vaultString
• zip
• azureServicePrincipal
• $class: 'AmazonWebServicesCredentialsBinding'

and more.

usernamePassword Binding - Injecting Username and Password into a Build Step

A typical pattern to project a username and a password stored as a Jenkins Username with Password credential into a build step:

withCredentials([usernamePassword(credentialsId: 'amazon', usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD')]) {
  sh 'echo $PASSWORD'
  echo USERNAME
  echo "username is $USERNAME"
}

The binding injects the username and the password read from the Jenkins credentials vault as environment variable and Groovy variables, available in the closure. If the credential entry whose ID is specified is not declared, the step fails with:

ERROR: Could not find credentials entry with ID 'test-credential'

Both the username and the password will be masked if printing is attempted:

[Pipeline] {
[Pipeline] withCredentials
Masking supported pattern matches of $USERNAME or $PASSWORD
[Pipeline] {
[Pipeline] sh
+ echo ****
****
[Pipeline] echo
****
[Pipeline] echo
Warning: A secret was passed to "echo" using Groovy String interpolation, which is insecure.
		 Affected argument(s) used the following variable(s): [USERNAME]
		 See https://jenkins.io/redirect/groovy-string-interpolation for details.
username is ****
[Pipeline] }
[Pipeline] // withCredentials

Configuration Map:

• credentialsId: the ID of the Jenkins credential that contains the username and password.
• usernameVariable:
• passwordVariable: