Credentials Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID credentials Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Feb 11, 2014
Source Code
Issue Tracking
Open Issues
Stephen Connolly (id: stephenconnolly)
Usage Installations 2013-Apr 22214
2013-May 31382
2013-Jun 36561
2013-Jul 42977
2013-Aug 46769
2013-Sep 50365
2013-Oct 56091
2013-Nov 57631
2013-Dec 57468
2014-Jan 63005
2014-Feb 65718
2014-Mar 70308

Credentials Plugin

This plugin allows you to store credentials in Jenkins.
The credentials plugin provides a standardized API for other plugins to store and retrieve different types of credentials. User visible features are:

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

As of version 1.5, the plugin now supports categorising credentials into different "domains" in order to allow plugins to restrict the choice of credentials to only those that are appropriate.

For example, you may use the same username with a different password on multiple services. e.g. Wile E Coyote may have an account with Acme Industries, Jenkins CI, etc. in each case using the same username but a different password.

If you need to select the credentials to use when connecting to a service, it can be difficult to ensure that you select the correct one. Selecting the wrong one may mean that the incorrect password triggers a service lockout.

Credential Domains are a solution to help with this problem.

When a plugin is asking for a list of credentials, it can add some specifications about where and how the credential will be used. If we configure the following Credential Domain:
And we are trying to make an update to the Acme wiki (e.g. then the plugin asking for credentials can say that it is looking for username/password credentials and it needs ones that support the https URI scheme, the hostname is and the port is 443. The credentials plugin will compare each credential domain's specification against the requirements and exclude any which do not match. Thus the user would be presented with the appropriate and relevant set of credentials.

When creating credential domains, it is important to note that domains are excluded based on requirements failing to match the specification. Thus if there is a specification for a specific URI scheme and the requirements do not detail a specific URI scheme then the credential domain is still considered to be a match. The logic is necessary to be this way in order to both allow existing plugins to retrieve credentials from within domains (even if they do not construct and supply a list of domain requirements) and also with the principle of allowing the user to be in control, i.e. the user can still select a credential if there is a possibility that the credential might apply, only where we know the credential is not appropriate do we exclude the domain.

Information for 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 callCredentialsProvider.lookupCredentials(type,item,auth,domainRequirements) 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 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).
The domainRequirements parameter is the list of requirements against which domain specifications will be verified when retrieving credentials.

Version History

Version 1.10 (Feb 11, 2014)

  • Add /api/ support
  • Add support for domain restricted credentials that can further restrict themselves within a domain

Version 1.9.4 (Dec 6, 2013)

  • Fixed issue with c:select and renderOnDemand on 1.500ish+ Jenkins instances (issue #20647)

Version 1.9.3 (Nov 8, 2013)

  • Minimum version of Jenkins is now 1.466
  • Added support for in-place adding of new credentials (JENKINS-20072)

Version 1.9.2 (Nov 8, 2013)

  • UI improvements and bugfixes

Version 1.9.1 (Oct 16, 2013)

  • Fix data binding issue with /lib/credentials/select.jelly

Version 1.9 (Oct 11, 2013)

  • Make DomainRequirement serializable as it may need to be transferred across remoting channels
  • Update to German L10N
  • Add a /lib/credentials/select.jelly taglib to make it possible to retrofit and add credentials UI to plugins that use this for selecting a credential from a drop-down list (note there is a bug in this version that is fixed in 1.9.1 where it fails to correctly prepare data-binding)

Version 1.8.3 (Sep 25, 2013)

Version 1.8.2 (Sep 13, 2013)

Version 1.8.1 (Sep 12, 2013)

  • Fixed some minor layout issues.
  • There is a bug in core with lazy rendering which will affect the ability to configure the credential scope via the new UI. Suspect this will require a fix in Jenkins core.

Version 1.8 (Sep 12, 2013)

  • Added an API to allow plugins to configure credentials
  • Added an abstract Action to allow credential stores which permit configuration of credentials to expose a user-space UI for credential management
  • Added distinct permissions for viewing the credential management UI; managing credential domains; adding credentials; removing credentials; and updating credentials.
  • Added the user space UI to the system credentials provider: JENKINS-19563

Version 1.7.6 (Aug 28, 2013)

  • Exception in Manage Credentials screen in 1.7.5.

Version 1.7.5 (Aug 28, 2013)

  • Fix issue with null values in domainCredentials.jelly taglib

Version 1.7.4 (Aug 22, 2013)

  • Include fix for JENKINS-19308
  • Add some more German translations

Version 1.7.3 (Aug 16, 2013)

Version 1.7.2 (Aug 15, 2013)

  • Fix naming of StandardUsernamePasswordCredentials

Version 1.7.1 (Aug 15, 2013)

  • Minor bug-fix in looking up names of credential instances.

Version 1.7 (Aug 15, 2013)

  • Provide a standard client certificate credential implementation type.

Version 1.6 (Aug 7, 2013)

  • Provide a standard username & password credential implementation type.
  • Add a builder for URI based domain requirements.
  • Add a ListBoxModel implementation to assist the common task of selecting a credential from a set of credentials.

Version 1.5 (Jul 23, 2013)

  • Add some common credential type marker interfaces
  • Add API support for filtering credentials
  • Add support for partitioning credentials into domains

Version 1.4 (Apr 15, 2013)

  • Add help page for scope.

 Version 1.3 (Feb 27, 2012)

  • Missed renaming a critical stapler view.

Version 1.2 (Feb 27, 2012)

  • Missed a critical constructor.

Version 1.1 (Feb 27, 2012)

  • Missed a couple of cosmetic references in open-sourcing this previously closed source plugin

Version 1.0 (Feb 27, 2012)

  • Initial release 
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment