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
1.24 (archives)
Oct 12, 2015
Source Code
Issue Tracking
Pull Requests
Open Issues
Pull Requests
Stephen Connolly (id: stephenconnolly)
Usage Installations 2014-Nov 92033
2014-Dec 92325
2015-Jan 96901
2015-Feb 98143
2015-Mar 106687
2015-Apr 106564
2015-May 106851
2015-Jun 112797
2015-Jul 116404
2015-Aug 115770
2015-Sep 119464
2015-Oct 122202

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 call CredentialsProvider.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.

Plugins that provide credentials

Page: Pushbullet Credentials Plugin — This plugin integrates Jenkins with Pushbullet.
Page: Plain Credentials Plugin — Allows use of plain strings and files as credentials.
Page: SSH Credentials Plugin — This plugin allows you to store SSH credentials in Jenkins.
Page: Google OAuth Plugin — This plugin implements the OAuth Credentials interfaces for surfacing Google Service Accounts to Jenkins.
Page: Docker Commons Plugin — APIs for using Docker from other plugins.
Page: Google Container Registry Auth Plugin — This plugin allows the credential provider to use Google Cloud Platform OAuth Credentials (provided by the Google OAuth Credentials plugin) to access Docker images from Google Container Registry (GCR).
Page: Config File Provider Plugin — Adds the ability to provide configuration files (i.e., settings.xml for maven, XML, groovy, custom files, etc.) loaded through the Jenkins UI which will be copied to the job's workspace.
Page: Rally plugin — This plugin allows pushing information to rally

If your plug-in is not listed here, then simply add the label credentials-provider to your plug-in wiki page and it will be automatically listed.

Plugins that consume credentials

Page: New Relic Deployment Notifier Plugin — Jenkins plugin to notify New Relic about deployments.
Page: GitHub pull request builder plugin — This plugin builds pull requests in github and report results.
Page: Config File Provider Plugin — Adds the ability to provide configuration files (i.e., settings.xml for maven, XML, groovy, custom files, etc.) loaded through the Jenkins UI which will be copied to the job's workspace.
Page: SSH Slaves plugin — This plugin allows you to manage slaves running on *nix machines over SSH.
Page: Ansible Plugin — This plugin allows to execute Ansible tasks as a job build step.
Page: Pushbullet Notifier Plugin — This plugin integrates Jenkins with Pushbullet.
Page: Phabricator Differential Plugin — Integrates with Phabricator's Differential and Harbormaster apps
Page: Subversion Plugin — This plugin adds the Subversion support (via SVNKit) to Jenkins.
Page: CloudBees Docker Build and Publish plugin
Page: Docker build step plugin — This plugin allows to add various Docker commands into your job as a build step
Page: XL TestView Plugin — The XL TestView Plugin integrates Jenkins with XebiaLabs XL TestView
Page: Rally plugin — This plugin allows pushing information to rally
Page: Credentials Binding Plugin — Allows credentials to be bound to environment variables for use from miscellaneous build steps.

If your plug-in is not listed here, then simply add the label credentials-consumer to your plug-in wiki page and it will be automatically listed.

Version History

Version 1.23 (Sep 7, 2015)

Version 1.22 (Jan 25, 2015)

  • Added a work-around for issue #26578 until the baseline version of Jenkins has fixed that issue

Version 1.21 (Jan 15, 2015)

  • JENKINS-26099 Allow the user to specify the ID of newly created credentials. (For username/password and certificate credentials. Credentials defined in other plugins need to use BaseStandardCredentialsDescriptor to pick up this feature.)
  • Suppressing a stack trace in case of a failure to unlock certificate credentials due to an empty password.

Version 1.20 (Dec 19, 2014)

Version 1.19 (Dec 18, 2014)

Version 1.18 (Oct 19, 2014)

  • UI glitch with icon tags

Version 1.17 (Oct 17, 2014)

  • Simplified handling of uploaded-file certificates on slaves.
  • Allowing parameter values to be used from workflow projects.
  • Improved Javadoc for list box models.
  • JENKINS-21051 Japanese translation fixes.
  • Exported description and displayName for use by REST API.

Version 1.16.1 (Aug 11, 2014)

  • Fix NPE in new parameter resolving helper method

Version 1.16 (Aug 11, 2014)

  • Add support for credentials parameters (note these are not exposed as environment variables, rather the IDs are exposed and plugin support is required to retrieve the credentials from the respective credential stores and act on those credentials as necessary)

Version 1.15 (Jul 10, 2014)

  • Fix the check for `isScopeRelevant(x) so that updating credentials within a credentials domain does not reset the scope to 'Global' (SECURITY-137

Version 1.14 (Jun 16, 2014)

  • Added support for snapshotting credentials.

Version 1.13 (May 30, 2014)

  • Added a defensive NPE check to UserCredentialsProvider to prevent log file spamming when using private security realm.

Version 1.12 (May 23, 2014)

  • Added a URI path domain requirement and specification to the standard API.

Version 1.11 (May 21, 2014)

  • Fix the permission scope to flag that credential store permissions are scoped to items, item groups and Jenkins and not limited in scope to just Jenkins.
  • Added an annotation to provide future assistance in identifying string fields that hold credential ids.

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 (JENKINS-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