Injecting Secrets into Jenkins Build Jobs

Jenkins customers commonly ask for tips about how to inject secrets into their build jobs.  This article summarizes the current best-practices for accomplishing this.

Install the Credentials Plugins

If you haven’t already, install the latest versions of these plugins into your Jenkins instance.

  • Credentials plugin - provides a centralized way to define credentials that can be used by your Jenkins instance, plugins and build jobs.
  • Credentials Binding plugin - allows you to configure your build jobs to inject credentials as environment variables.
  • Plain Credentials plugin - a plugin dependency required by the Credentials Binding plugin.

Note: If you do not see these plugins in your list of available plugins, try refreshing the list of available plugins using the [Check now] button on the Advanced tab of the plugin management page. Also, be sure to restart Jenkins after installing the plugins.

Defining Credentials and Secrets

After installing the credentials plugins, your Jenkins sidebar will contain a new *Credentials* page that can be used to define credentials and secrets. The easiest way to define secrets for use in your build jobs is to:

  • Click the **Credentials** link in the sidebar
  • Click on the **Global credentials** domain 
  • Click [**Add Credential**]
  • Select a credential kind that can be used from your build jobs (later, using a credentials binding). The following types of credentials are most useful to use from your build jobs.
    • Username with password - a username/password pair
    • usernamepassword.png
    • Secret file - an uploaded file
    • secretfile.png
    • Secret text - a raw secret string
    • secrettext.png

Note: be sure keep the default “Global” scope for credentials that need to be accessible to build jobs. 

Note: be sure to specify the ID for the credential because that is how it is referenced in the job when using the
parameter expression option. 

Using Credentials and Secrets from Build Jobs

After installing the Credentials Bindings plugin, the *Build Environment* section of your build job *Configuration* page will include a new option to “Use secret text(s) or file(s)”. Enabling this option allows you add credential bindings where the *Variable* value will be used as the name of the environment variable that your build can use to access the value of the credential.

Normally you will start your script with

set +x

so that commands you run are not echoed to the log, in case you mention the values of secrets in those commands.

The credential value will vary based on the kind of credential:

Secret text bindings are injected as a raw secret string

Shell example: Echo a secret text binding

# MY_SECRET is injected from a secret text binding as defined in Credentials.
echo "My secret is $MY_SECRET"

secrettextshell.png

secrettextoutput.png

Username with password bindings are injected as a **username:password** formatted string

Shell example: Split a username and password binding into variables named MY_USERNAME and MY_PASSWORD.

# MY_SECRET_USER injected from username and password binding
# The username and password can be conjoined or separated
MY_USERNAME=`echo $MY_SECRET_USER` #separated example
MY_PASSWORD=`echo $MY_SECRET_USER_PASSWORD` #separated example
MY_USERNAME and MY_PASSWORD=`echo $MY_CREDENTIALS` #conjoined example

conjoinedshell.png

conjoinedoutput.png

separtedshell.png

separatedoutput.png

Secret file bindings are injected as filesystem path to the uploaded secret file

Shell example: Read the data from a secret file binding into a local variable

# MY_SECRET_FILE path injected from secret file binding

MY_FILE_DATA=`cat $MY_SECRET_FILE`
echo "The secret file data is: $MY_FILE_DATA"

secretfileshell.png

secretfileoutput.png

Using Folders to control Credential usage

In larger build environments, it may be preferable to avoid putting all credentials into the Global domain (where they can be used by any build) and instead make it so that only some build jobs have access to certain credentials. This can be accomplished using the Folders plugin. The Credentials plugin is folder-aware and will enhance the Configure page for Folders with a Credentials section. Credentials defined on a folder can only be used by builds within that folder.

You can further secure access to credentials to only specific users in your organization by combining the Credentials and Folder plugins with theRole Based Access Control plugin (available via CloudBees Jenkins Enterprise or DEV@cloud).

Alternative ways to inject build variables

Have more questions? Submit a request

6 Comments

  • 0
    Avatar
    Michael Klöckner
    It worked like a charm for me even on an OSS Jenkins installation. I just had to install another plugin to make it work: CloudBees Credetnials Plugin.
  • 0
    Avatar
    Alan Villa

    Is it possible to inject credentials when invoking Ant in Jenkins?

  • 0
    Avatar
    Peter Carr

    re: Ant,

    It possible to load a properties file from an ant script; in theory you could load a secret file.

    Note: I am not using this yet from Jenkins ... because I am browsing this thread to learn how!

  • 0
    Avatar
    Paul Grove

    As this article states this is "current best-practices" maybe then some effort should be made to kill the bugs of the credential bind plugin that makes the best practice insecure. See https://issues.jenkins-ci.org/browse/JENKINS-24805 open for 2 years. Due to this the plugin is disabled in our company, leading to yet more hack workarounds that sap our time. Please fix!

  • 0
    Avatar
    Jj Cm

    Totally agree with Paul.

    The issue  https://issues.jenkins-ci.org/browse/JENKINS-24805 seems to be solved, and credentials are now masked on the console output of a job log. However, a simple "echo $MY_SECRET > secret.txt" shows the secret into a text file on the workspace.

    Please fix !

     

  • 1
    Avatar
    Jesse Glick

    Jj Cm: as designed. Masking only exists to reduce the chance of accidental disclosure.

Please sign in to leave a comment.