Credentials Binding Plugin

The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Table of Contents

Credentials Binding Plugin
- withCredentials: Bind credentials to variables

Credentials Binding Plugin

View this plugin on the Plugins site

`withCredentials`: Bind credentials to variables

Allows various kinds of credentials (secrets) to be used in idiosyncratic ways. (Some steps explicitly ask for credentials of a particular kind, usually as a credentialsId parameter, in which case this step is unnecessary.) Each binding will define an environment variable active within the scope of the step. You can then use them directly from any other steps that expect environment variables to be set:

node {
  withCredentials([usernameColonPassword(credentialsId: 'mylogin', variable: 'USERPASS')]) {
    sh '''
      set +x
      curl -u "$USERPASS" https://private.server/ > output
    '''
  }
}

As another example (use Snippet Generator to see all options):

node {
  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
    sh '''
      set +x
      curl -H "Token: $TOKEN" https://some.api/
    '''
  }
}

Note the use of single quotes to define the script (implicit parameter to sh) in Groovy above. You want the secret to be expanded by the shell as an environment variable. The following idiom is potentially less secure, as the secret is interpolated by Groovy and so (for example) typical operating system process listings will accidentally disclose it:

node {
  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
    sh /* WRONG! */ """
      set +x
      curl -H 'Token: $TOKEN' https://some.api/
    """
  }
}

At least on Linux, environment variables can be obtained by other processes running in the same account, so you should not run a job which uses secrets on the same node as a job controlled by untrusted parties. In any event, you should always prefer expansion as environment variables to inclusion in the command, since Jenkins visualizations such as Blue Ocean will attempt to detect step parameters containing secrets and refuse to display them.

The secret(s) will be masked (****) in case they are printed to the build log. This prevents you from accidentally disclosing passwords and the like via the log. (Bourne shell set +x, or Windows batch @echo off, blocks secrets from being displayed in echoed commands; but build tools in debug mode might dump all environment variables to standard output/error, or poorly designed network clients might display authentication, etc.) The masking could of course be trivially circumvented; anyone permitted to configure a job or define Pipeline steps is assumed to be trusted to use any credentials in scope however they like.

Beware that certain tools mangle secrets when displaying them. As one example, Bash (as opposed to Ubuntu’s plainer Dash) does so with text containing ' in echo mode:

$ export PASS=foo"'"bar
$ env|fgrep PASS
PASS=foo'bar
$ sh -xc 'echo $PASS'
+ echo foo'bar
foo'bar
$ bash -xc 'echo $PASS'
+ echo 'foo'\''bar'
foo'bar

Mangled secrets can only be detected on a best-effort basis. By default, Jenkins will attempt to mask mangled secrets as they would appear in output of Bourne shell, Bash, Almquist shell and Windows batch. Without these strategies in place, mangled secrets would appear in plain text in log files. In the example above, this would result in:

+ echo 'foo'\''bar'
****

This particular issue can be more safely prevented by turning off echo with set +x or avoiding the use of shell metacharacters in secrets.

For bindings which store a secret file, beware that

node {
  dir('subdir') {
    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
      sh 'use $FILE'
    }
  }
}

is not safe, as $FILE might be inside the workspace (in subdir@tmp/secretFiles/), and thus visible to anyone able to browse the job’s workspace. If you need to run steps in a different directory than the usual workspace, you should instead use

node {
  withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
    dir('subdir') {
      sh 'use $FILE'
    }
  }
}

to ensure that the secrets are outside the workspace; or choose a different workspace entirely:

node {
  ws {
    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
      sh 'use $FILE'
    }
  }
}

Also see the Limitations of Credentials Masking blog post for more background.

bindings
- aws
  Sets one variable to the AWS access key and another one to the secret key given in the credentials.
  - accessKeyVariable
    Environment variable name for the AWS Access Key Id. If empty, AWS_ACCESS_KEY_ID will be used.
    - Type: String
  - secretKeyVariable
    Environment variable name for the AWS Secret Access Key. If empty, AWS_SECRET_ACCESS_KEY will be used.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - roleArn (optional)
    - Type: String
  - roleSessionDurationSeconds (optional)
    - Type: int
  - roleSessionName (optional)
    - Type: String
- token
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- $class: 'AwsBucketCredentialsBinding'
  Does something.
  - usernameVariable
    - Type: String
  - passwordVariable
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- certificate
  Sets one variable to the username and one variable to the password given in the credentials.
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the text of the secret, for example on Linux using ps e.
  - keystoreVariable
    Name of an environment variable to be set to the temporary keystore location during the build. The contents of this file are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - aliasVariable (optional)
    Name of an environment variable to be set to the keystore alias name of the certificate during the build.
    - Type: String
  - passwordVariable (optional)
    Name of an environment variable to be set to the password during the build.
    - Type: String
- ConjurSecretApplianceCredentials
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - sPath (optional)
    - Type: String
  - variable (optional)
    - Type: String
- conjurSecretCredential
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - variable (optional)
    - Type: String
- conjurSecretUsername
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - passwordVariable (optional)
    - Type: String
  - usernameVariable (optional)
    - Type: String
- conjurSecretUsernameSSHKey
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - secretVariable (optional)
    - Type: String
  - usernameVariable (optional)
    - Type: String
- dockerCert
  - variable
    Name of an environment variable to be set during the build.
    Its value will be the absolute path of the directory where the {ca,cert,key}.pem files will be created.
    You probably want to call this variable DOCKER_CERT_PATH, which will be understood by the docker client binary.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- file
  Copies the file given in the credentials to a temporary location, then sets the variable to that location. (The file is deleted when the build completes.)
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the contents of this file.
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- gitUsernamePassword
  - gitToolName
    
    Specify the Git tool installation name
    - Type: String
  - credentialsId
    Set the git username / password credential for HTTP and HTTPS protocols.
    Shell example
    
    withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) { sh 'git fetch --all' }
    
    Batch example
    
    withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) { bat 'git submodule update --init --recursive' }
    
    Powershell example
    
    withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) { powershell 'git push' }
    - Type: String
- $class: 'KeychainPasswordAndPathBinding'
  - keychainPathVariable
    Name of a variable that contains information about the keychain path stored in the 'Credentials'.
    Because values are stored in the environment variable of the name specified here, you can use the information stored in the 'Credentials' by shell script etc.
    - Type: String
  - passwordVariable
    Name of a variable that contains information about the keychain password stored in the 'Credentials'.
    Because values are stored in the environment variable of the name specified here, you can use the information stored in the 'Credentials' by shell script etc.
    - Type: String
  - inSearchPathVariable
    Name of a variable that stores information on whether to set the keychain stored in the 'Credentials' to the search path.
    Because values are stored in the environment variable of the name specified here, you can use the information stored in the 'Credentials' by shell script etc.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- kubeconfigContent
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- kubeconfigFile
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- OSFBuilderSuiteOpenCommerceAPICredentials
  - clientIdVariable
    - Type: String
  - clientPasswordVariable
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- sshUserPrivateKey
  Copies the SSH key file given in the credentials to a temporary location, then sets a variable to that location. (The file is deleted when the build completes.) Also optionally sets variables for the SSH key's username and passphrase.
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the contents of this file.
  - keyFileVariable
    Name of an environment variable to be set to the temporary path of the SSH key file during the build. The contents of this file are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - passphraseVariable (optional)
    Name of an environment variable to be set to the password during the build. (optional)
    - Type: String
  - usernameVariable (optional)
    Name of an environment variable to be set to the username during the build. (optional)
    - Type: String
- string
  Sets a variable to the text given in the credentials.
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the text of the secret, for example on Linux using ps e.
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- OSFBuilderSuiteTwoFactorAuthCredentials
  - serverCertificateVariable
    - Type: String
  - clientCertificateVariable
    - Type: String
  - clientPrivateKeyVariable
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- usernameColonPassword
  Sets a variable to the username and password given in the credentials, separated by a colon (:).
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the text of the secret, for example on Linux using ps e.
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- usernamePassword
  Sets one variable to the username and one variable to the password given in the credentials.
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the text of the secret, for example on Linux using ps e.
  - usernameVariable
    Name of an environment variable to be set to the username during the build.
    - Type: String
  - passwordVariable
    Name of an environment variable to be set to the password during the build.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- $class: 'VaultCertificateCredentialsBinding'
  Certificate Jenkins credential backed by a Hashicorp Vault secret
  - keyStoreVariable
    - Type: String
  - passwordVariable
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- vaultFile
  Secret File Jenkins credential backed by a Hashicorp Vault secret
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- $class: 'VaultSSHUserPrivateKeyBinding'
  SSH Username with private key credential backed by a Hashicorp Vault secret
  - usernameVariable
    - Type: String
  - privateKeyVariable
    - Type: String
  - passphraseVariable
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- vaultString
  Secret Text Jenkins credential backed by a Hashicorp Vault secret
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- $class: 'VaultTokenCredentialBinding'
  - addrVariable
    The environment variable to set with the vault address.
    - Type: String
  - tokenVariable
    The environment variable to set with the vault token.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - vaultAddr
    The vault address where the credentials are to be used.
    - Type: String
  - namespaceVariable (optional)
    - Type: String
  - vaultNamespace (optional)
    - Type: String
- $class: 'VaultUsernamePasswordCredentialBinding'
  Username/ Password Jenkins credential backed by a Hashicorp Vault secret
  - usernameVariable
    - Type: String
  - passwordVariable
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- zip
  Unpacks the ZIP file given in the credentials to a temporary directory, then sets the variable to that location. (The directory is deleted when the build completes.)
  
  Warning: if the Jenkins controller or agent node has multiple executors, any other build running concurrently on the same node will be able to read the contents of this directory.
  - variable
    Name of an environment variable to be set during the build. The contents of this location are not masked.
    - Type: String
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
- azureServicePrincipal
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - clientIdVariable (optional)
    - Type: String
  - clientSecretVariable (optional)
    - Type: String
  - subscriptionIdVariable (optional)
    - Type: String
  - tenantIdVariable (optional)
    - Type: String
- azureStorage
  - credentialsId
    Credentials of an appropriate type to be set to the variable.
    - Type: String
  - blobEndpointUrlVariable (optional)
    - Type: String
  - storageAccountKeyVariable (optional)
    - Type: String
  - storageAccountNameVariable (optional)
    - Type: String

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

User Handbook

Tutorials

Resources

Credentials Binding Plugin

`withCredentials`: Bind credentials to variables

Resources

Project

Community

Other

User Handbook

Tutorials

Resources

Credentials Binding Plugin

withCredentials: Bind credentials to variables

`withCredentials`: Bind credentials to variables