Topics

  1. Architecture  
  2. Initialization and Startup  
  3. Extensibility  
  4. Model  
  5. Handling Requests  
  6. Security  
  7. Persistence  
  8. Scheduling  
  9. Views  
  10. Forms  
  11. Internationalization and Localization  
  12. Distributed Builds  
  13. Jenkins CLI  
  14. Testing  
  15. Plugin development  
  16. Publishing Plugins
  17. Blue Ocean  
  18. Building and Debugging  
  19. Setting up a Development Environment  

How-To Guides

Resources

Extensions Index
Javadoc
Taglibs
Tools

Storing Secrets

View the index of available developer guides

Plugins commonly store user credentials and similar secrets, like API keys, access tokens, or just user names and passwords, to interface with other systems and services. Plugins that store such secrets need to be careful how they store them. With simple String fields that get serialized to disk as plain text, a number of problems can occur:

  • On many systems, large parts of the Jenkins home directory is accessible to other user accounts, allowing to retrieve credentials stored on disk as plain text.

  • Backups of Jenkins home can be compromised, disclosing secrets, even when excluding the secrets/ directory.

  • String fields are round-tripped in configuration forms as plain text even if the value is hidden in a password field, so can be accessed via the HTML page source code. This even applies to users who only have the Extended Read permission.

The easiest solution to all of the above is to store the password as a Secret.

  • The key to decrypt secrets is stored in the secrets/ directory which has the highest protection, and is recommended to be excluded from backups.

  • Secret fields are round-tripped in their encrypted form, so that their plain-text form cannot be retrieved by users later. If a user only has the Extended Read permission, the secret is simply removed from output.

A more advanced option is to integrate with Credentials Plugin. See its documentation for more information.

Storing Secrets on Disk

The easiest way to store secrets is to store them in a field of the type Secret. Jenkins will transparently handle the encryption and decryption.

Secrets and Configuration Forms

In the configuration form, display the secret itself (rather than the decrypted secret) hidden in a <f:password> field.

Secrets spanning multiple lines (such as certificates or SSH keys) should be masked from view by using the <f:secretTextarea> form element. It is available from Jenkins 2.171. Plugins with older core baselines can add a dependency on the standalone library io.jenkins.temp.jelly:multiline-secrets-ui:1.0 (or newer) with the same form element. See the documentation in its GitHub repository for usage instructions and sample code.