Use credentials to secure access to external sites and applications that can interact with Jenkins such as artifact repositories, cloud-based storage systems and services, and databases. This is both more secure and more convenient than hard coding username and password or other authentication devices in each Pipeline.

This page summarizes the best practices for securing your credentials.

Working with Credentials

Implementing credentials has two elements:

Limit Access to Credentials

Limit the scope of who has access to the credentials. This minimizes the attack surface. You should "build from the bottom". In other words, start with no access to the credentials and then grant access to specific people and projects rather than granting access to everyone and then removing some grants. Specifically:

  • Severely limit the number of people with Credentials > Create permissions.

  • Grant access only to specific people, projects, and items that actually require this access to do their jobs.

  • Define each credential at the lowest possible level. Credentials defined for the controller are available to all Pipelines run by that controller. Credentials defined for a folder are only available to Pipelines run from that folder. The screens used to add and manage credentials for controllers and folders are identical except for their location.

Protect Secrets

Keys to decrypt secrets are stored in the $JENKINS_HOME/secrets/ directory. This directory has restrictive Linux file system permissions and should be carefully protected:

  • You must be able to retrieve your secrets if you need to restore your instance.

  • If someone were to get access to your backups as well as the secret, they would have full access to your entire Jenkins instance and everything it accesses.

The following practices are recommended to ensure that your secrets are kept secret:

  • Never include the secrets directory in a backup of your instance.

  • Do not store keys in the SCM where their contents could be breached.

    • A disk crash or data corruption for your application could cause the loss of all the encrypted information for your instance.

    • If someone breaches your SCM and your secrets are there, they have full access to your Jenkins instance.

  • Instead, keep a copy of the secrets in a location apart from other backups and copies of your application. The secret is small and never changes after it is created. You can manually re-add it when restoring from backup.

Other Notes about Credentials

  • Modify the underlying credentials (username/password, secret text, etc) frequently.

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.