by
tags:

How to mask credentials in your Jenkins jobs

jenkins logo

Some build processes may require you to supply username and password as part of the build process.

For example, let's say that you want to configure a Jenkins build process which requires downloading a source.zip file from a private git repository as part of the build process. The last thing that you want to do is to write the username and password in cleartext as it will be shown on Jenkins build log when the job runs.

This article covers the steps to mask credentials in freestyle and pipeline projects, click the below links to jump straight to the topic:

Masking credentials in a Freestyle project

Masking credentials in a Pipeline project

Prerequisites

  • A Jenkins server.
  • Required privileges on Jenkins to install plugins and create a project.

Download required plugins

You will need to download and install three Jenkins plugins:

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

When all three plugins are installed your Jenkins installation has the required directives to allow you to inject secrets into Jenkins.

Create credentials

Go to Jenkins (menu) and choose Credentials.

Create a new user and password credentials (I've created a credential for my git user) and once it's created copy it's credentials ID - This is a hash which is used by Jenkins to identify these specific credentials.

Masking credentials in a Freestyle project

Create and configure your new build job

Create a new item (new job) , name it and select "Freestyle project".

After installing the plugins you will now have a new option under "Build Environment" which is called "Use secret text(s) or file(s)", check it and a new box will appear - "Bindings" and under it "Add".

build environment

For this example I've created a credentials set for a git user, meaning username and password.

Click Add and choose "Username and password (separated)":

username and password

A new box will appear where you can insert the variable name which will hold the real username as in the credentials and the variable name for the password which will hold the real password as in the credentials.

set user and pass variables

Now you can use the variables we've configured in your shell script.

Testing your configuration

I've added an "Execute shell" build step which looks like that:

echo ${GIT_USER}
echo ${GIT_PASS}

And when I run it, you can see that the username and password are masked:

freestyle test

That is how you configure masked credentials in a Freestyle project.

Masking credentials in a Pipeline project

In order to mask usernames and passwords in a Pipeline project, I've created a new Pipeline project and in the Pipeline syntax box I've inserted the following code:

def git_creds = 'fb85701a-9f10-4056-9ae7-420e3XXXX9ef'
node {
  withCredentials([
      [$class: 'UsernamePasswordMultiBinding', credentialsId: git_creds, usernameVariable: 'GIT_USER', passwordVariable: 'GIT_PASS'],
  ]){
    stage ('echo variables') {
      sh """(
        echo "User: ${GIT_USER}"
        echo "Pass: ${GIT_PASS}"
      )"""
    }
  }
}

The above groovy code sets the variable which is called "git_creds" with the actual credentialsID of the username and password that I've created earlier in the article.

Then, in the "withCredentials" closure you can see how I bind "GIT_USER" and "GIT_PASS" variables to the actual values which are accessed by their CredentialsID.

Last step is the test, I'm using a shell execute build step to print both of the variables and make sure they're masked.

Example:

pipeline project

Masking credentials like I showed in this article allows me to run a command like that in order to download a file while specifying masked credentials:

wget --auth-no-challenge --user=${GIT_USER} --password=${GIT_PASS} https://bitbucket.org/company/repository/get/$DEPLOY_TAG.zip

Written by: Itai Ganot, 2017

E-Mail: itaig@tikalk.com