Open Sourcing the Credentials Plugin

Written by: Stephen Connolly

Jenkins I thought we would start off with

A story...

A team is just starting off on a new project, getting things done is the priority.

Source control, minor scuffle as the team argues the relative merits of Subversion, Git, Mercurial... (the one lone CVS fan storms off with a bruised ego and maybe more). A winner is declared and somebody sets it up.

Access control, well just give everyone on the team an account and give them all the same password: “password123”, so that password forgetting and subsequent resets will not be a problem. Anyway, it's a small team that trusts each other.

Continuous integration, somebody downloads Jenkins, grabs a spare machine, stuffs it under their desk... 5 minutes later... up and running.

Jenkins needs the source control password to do some task or other.  Well, it's “password123” no big deal, sure everyone knows that password.

At some point in time, the bureaucrats enter the scene, and this cozy little “password123” realm gets disbanded.

Now source control is integrated with some corporate LDAP or other scheme providing the glorious single sign-on.

The password Jenkins uses to access source control changes every 30 or 60 or 90 days, and somebody has to run around the Jenkins user interface on “password change day” changing that password from “$cr3wITp0licyJan12” to “$cr3wITP0licyFeb12” hoping they have not missed one of the many places Jenkins stores password (email auth, scm auth, issue tracker auth, etc) before Jenkins tries for the 5th (or 3rd) time with the wrong password and the account gets locked out and needs a reset (with a repeat run around).


If any of this sounds familiar, then CloudBees releasing our Credentials plugin for Jenkins as Open Source will be the first step along the road to a better solution.

It's not the complete solution, only because all the current Jenkins plugins that store credentials will need some modification to use the credentials plugin, but those changes should be minor.

What does the Credentials Plugin do (for users)?

The credentials plugin provides a standardized API for other plugins to store and retrieve different types of credentials. If you were to take a stock Jenkins installation and just install the credentials plugin, you wouldn't see anything different... to see something different you would need to install a plugin that defines a type of credential. Once you did that you would find:

  • A “Manage Credentials” screen on the “Manage Jenkins” screen allowing you to manage system and global credentials.
  • If you are using Jenkins security, when you go to “Users” / your username / “Configure” you would see the option to manage personal credentials.
  • Anywhere those credentials are needed, there is a drop down list of the appropriate available credentials, and you just select the appropriate one.
  • When the time comes to change the password, you just change it once. 

And that is about it, from the end-user's perspective. A single point for managing each credential. Change it in one place and you are done.

What does the Credentials Plugin do (for Jenkins plugin developers)?

The credentials plugin provides two main extension points:

  • Credentials - a base class for all Credentials types managed by the credentials plugin. Most plugin authors will just want to subclass this type to define what they need to store in the credential type... better yet, if you can find an existing Credentials subclass that stores your credentials.  So, for example, if somebody created a ssh-credentials plugin that just defines a SshCredentials class, then anyone needing ssh credentials could just depend on that... [Note that careful use of readResolve can allow this to be introduced after the fact]
  • CredentialsProvider - an extension point for something that can provide credentials. For example, the CloudBees Folders plugin uses this extension point to provide folder scoped credentials, so that the credentials are only available to jobs within the folder.

When you need to get back some credentials you just call CredentialsProvider.lookupCredentials(type,item,auth) to retrieve the appropriate credentials. 

The type parameter is the class of credentials you want to retrieve. 

The item parameter is the job you want to retrieve the credentials for, but this could also be the Jenkins instance itself; e.g., if getting the email credentials when Jenkins is sending emails, if getting the ssh credentials for Jenkins to start a slave node with, etc.

The auth parameter is the authentication that is requesting the credentials. In general this will be ACL.SYSTEM but, for example, the soon to be released version 2.0 of the CloudBees Deployer plugin adds a “Deploy Now” action which allows a user to use their own user-scoped credentials to deploy an already built web application to their own RUN servlet container instance (useful for testing older builds to see if you have a valid test case for that bug).

Why are we releasing this plugin open source?

Jenkins needs this functionality, and releasing it as open source lets the community retrofit all the existing plugins with confidence that the source is in the open and not CloudBees proprietary.

Where is the source and when is the source available?

Simple: and now ;-)

Relevant documentation


- Stephen Connolly , Elite Developer and Architect



Stay up to date

We'll never share your email address and you can opt out at any time, we promise.